Documentation Quickstart

Contents

Documentation Quickstart#

We have recently converted our documentation to use Jupyter Book, which plays nicely with our documentation hosting service Read the Docs. A key motivation in doing so is to enable first class support for executable code cells and even full Jupyter notebooks!

Jupyter Book uses MyST (Markedley Structured Text) Markdown (see their overview for details). MyST supports many of the same reStructuredText directives already in use within PDAL’s documentation, though the look and feel of the raw docs will certainly have more of Markdown feel to them.

Rather than provide our own Jupyter Book and MyST markdown overview, we’ll encourage developers to visit the respective projects to learn more. And be sure to browse our new docs to familiarize yourself with how we have adopted it.

Some key points to remember when writing documentation.

  1. Start by creating a new .md file within the doc folder and populating it with your desired content.

  2. Next (or first, it doesn’t really matter!), take a look at _toc.yml and add a reference to your new file where you would like it to appear within the rendered docs. More on the TOC and structure of Jupyter Books here.

  3. If your documentation has any references cited, be sure to add the corresponding BibTex entry to references.bib at the root of the doc folder.

  4. If you have added executable content to your docs and it requires a new package, please add it to environment.yml at the root of the doc folder so that Read the Docs will be able to properly setup the environment.

  5. Documentation is automatically built for each GitHub Pull Request commit. You can always preview the rendered documentation by following the links in the pull request.

  6. Documentation can be built locally as well using the Jupyter Book CLI. I’m currently using the following Mamba environment to setup my environment. Once your environment is setup and jupyter-book is installed, you should be able to simply run jb build doc.

    name: jb-build-pdal-docs
channels:
- conda-forge
dependencies:
- python-pdal
- jupyter-book
- ca-certificates
- certifi
- openssl
- sphinx-notfound-page
- sphinxcontrib-jquery
- sphinxcontrib-bibtex

Pixi Update#

PDAL has begun to adopt pixi for many tasks. This is awesome news for the documentation! Instead of following the steps outlined in step 6 above, you can now run the following command from the root of the PDAL repository.

pixi run -e doc build
pixi run -e doc preview

If adding dependencies required for building the documentation, as in step 4, the process is slightly different. While it is convenient to add a new dependency using

pixi add mynewdependency

this will add the dependency to the default environment, whereas we build in a custom doc environment. The current solution will be to add a new line under

[feature.doc.dependencies]
...existing dependencies...
mynewdependency = "*"

in the pixi.toml manifest. Of course, if specific versions are required, this can be specified using the VersionSpec.

Contents