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


  • 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


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

$ ./        # convience script
$ sphinx-build -b doctest source build  # run tests manually



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

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

See sphinx-build docs for more options.


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
$ 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


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:

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

And the visit the webpage served at 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.


  • /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/ - 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