Building the documentation#
Coding and documentation standards#
Lightkurve adopts AstroPy’s coding guidelines and standards, as documented in AstroPy’s Development Documentation.
Building documentation#
Note
Building the documentation is not necessary unless you are writing new documentation or do not have internet access, because the latest version of the documentation is available online at docs.lightkurve.org .
Building the lightkurve documentation requires sphinx and a few extra packages. We recommend using poetry to install the development dependencies:
$ poetry install
To make a clean directory for the docs use:
$ cd docs
$ make clean
To build the documentation in HTML format, execute:
$ cd docs
$ make html
Note if you build the documentation after cleaning the directory this will compile the notebooks, which can take a significant amount of time (over 30 minutes). This will save the documentation website in the ../../lightkurve-docs directory
on your system. If you re-run the make html command the notebook-based tutorials will not be recompiled by default
because they take some time to build. To recompile the just the notebooks, type:
$ make notebooks
Finally, if you have write permission to lightkurve’s GitHub repository, you can upload the documentation to the web server using:
$ make upload
Note
If you encounter the error Pandoc wasn't found, you will have to install pandoc separately as well following its installation instruction .
For example, on Mac OS you can install pandoc using homebrew:
$ brew install pandoc
An alternative method is to install pandoc using conda:
$ conda install --channel=conda-forge pandoc
Note
To build the docs on a Mac you may have to install the Xcode Command Line Tools, which you can do using:
$ xcode-select --install