Documentation

The following sections outlines how to develop and build the podpac documentation.

Install

  • Install Sphinx and the Read the Docs theme
$ conda install sphinx              # or `pip install sphinx`
$ conda install sphinx_rtd_theme    # or `pip install sphinx-rtd-theme`
  • Install recommonmark to support markdown input files
$ pip install recommonmark

Test

To run the doctests in the documentation, run from the /doc directory:

$ ./test-docs.sh        # convience script
or
$ sphinx-build -b doctest source build  # run tests manually

Build

Website

To build the documentation into a website in the doc/build directory, run from the /doc directory:

$ make html
or
$ sphinx-build source build       # run manually
$ sphinx-build -aE source build   # rebuild all files (no cache)

See sphinx-build docs for more options.

PDF

To build a pdf from the documentation, you need to install a latex distribution (MikTex (Windows) MacTex (Mac)), then run:

$ make latex                           # build the docs into a tex format in a latex directory
or
$ sphinx-build -b latex source latex   # run sphinx manually to build lated b

Enter the build directory and convert tex file to pdf:

$ cd build                             # go into the latex directory
$ pdflatex podpac.tex          # build the pdf from podpac.tex entry file

Develop

To live-serve the documentation as a website during development, you will need to add one more python package sphinx-autobuild:

$ pip install sphinx-autobuild

Then run from the doc directory:

$ ./serve-docs.sh                   # convience script
or
$ sphinx-autobuild source build     # run manually
$ sphinx-autobuild -aE source build # rebuild all files (no cache)

And the visit the webpage served at http://127.0.0.1:8000. Each time a change to the documentation source is detected, the HTML is rebuilt and the browser automatically reloaded.

To stop the server simply press ^C.

Organization

  • /source - source documentation files
    • /source/_templates - templates to use for styling pages
    • /source/_static - static files that need to be copied over to distributed documentation (i.e. images, source code, etc)
    • /source/conf.py - sphinx configuration file
    • /source/index.rst - root documentation file. Includes TOC
    • /source/user/api/ - auto generated API documentation using sphinx-autogen
    • /source/user/api-min/ - auto generated minimal API documentation using sphinx-autogen
    • … add others as generated …
  • /build - generated documentation files