Skip to content

howto_build_docs.md

Latest commit

 

History

History
119 lines (84 loc) · 3.28 KB

howto_build_docs.md

File metadata and controls

119 lines (84 loc) · 3.28 KB

Building the SketchResponse Documentation

There are two sets of documentation that need to be generated as the software changes: the API documentation and the Usage documentation. The API docs are build from the grader library source code using Sphinx. The usage docs are built from the markdown in the /docs directory using Gitbook.

## Building the API documentation
  1. The first step to building the API documentation is installing Sphinx. The easiest way to do this is to install using pip.
$ pip install sphinx
  1. Change directory to /docs/apidocs/
$ cd docs/apidocs/
  1. Make sure all the relevant grader library modules are listed in the grader_lib.rst. This is the configuration file that tells sphinx where and how to extract docstrings from the source code.
  2. Generate static html from the source. This will create the static html for the api docs in the directory _build/html/.
$ make html
  1. Generate a pdf copy of the api docs. This will generate a pdf using latex in the directory _build/latex/. We will move this into the docs/assets directory for use when we build the usage docs.
$ make latexpdf
$ mv _build/latex/SketchResponse.pdf ../assets/SketchResponseAPI.pdf
  1. Checkout the gh-pages branch.
$ git checkout gh-pages
  1. Move the new docs to the top level directory.
$ rsync -a _build/html/ ../..
  1. Commit and push all the modified files.
$ git commit -a -m "informative commit message here"
$ git push
  1. And you are done. Checkout master (or whatever other branch you prefer).
$ git checkout master
## Building the Usage documentation
  1. The first step in building the usage documentation is installing Gitbook. Gitbook requires NodeJS to install since Gitbook is an npm package. You will also need Calibre installed because we will need ebook-convert to generate the pdf version of the gitbook. Follow the instructions here to install Calibre and make ebook-convert accessible on your PATH.
$ npm install gitbook-cli -g
  1. Change directory to the root of the SketchResponse repository.
$ cd ../..
  1. Build the pdf. This will create a pdf copy of the docs in the current direcotry.
$ gitbook pdf ./ ./docs/assets/SketchResponse.pdf
  1. Build the docs. This will create the html in the directory _book.
$ gitbook build
  1. Clone or pull down the lastest copy of the SketchResponse github.io page.
$ cd ..
$ git clone https://github.com/SketchResponse/SketchResponse.github.io.git

or

$ cd ../SketchResponse.github.io
$ git pull
  1. Change back into the sketchresponse directory and copy the new files to the github.io repository.
$ cd ../sketchresponse
$ rsync -a _book/ ../SketchResponse.github.io/
  1. Change directory to the github.io reponsitory, add any new files that were not a part of an older version of the document, commit and push all changes.
$ cd ../SketchResponse.github.io
$ git add <list of files that are new>
$ git commit -a -m "informative commit message here"
$ git push
8. That's it. You are done.