search

csp-inc / fluvius

Collaboration project with Analytics Lab at CSP, Instituto Tecnologico Vale, and Microsoft Brazil for estimating suspended sediment in the Itacaiunas River Basin
https://csp-inc.github.io/fluvius/
Apache License 2.0
3 stars 1 forks source link

Develop complete draft of docs pages #35

Open lzachmann opened 2 years ago

lzachmann commented 2 years ago

We are using GitHub Actions to do two things: 1) build the Docker image we are using for this work (which is now available for download or use in other actions via the container registry: https://github.com/orgs/csp-inc/packages/container/package/fluvius), and 2) use this image to compile the project docs using Sphinx.

Contributing to the docs

Local development (recommended)

From 'docs/' directory in a shell running in the container, run make clean html. Sphinx uses the 'instructions' in 'docs/source' to build the site. We serve the site from 'docs/build/html/' using GitHub Pages on an orphaned gh-pages branch.

On the remote

Commits pushed to any of the paths / branches specified in the gh-pages.yml workflow (https://github.com/csp-inc/fluvius/blob/ljz/dev/.github/workflows/gh-pages.yml#L5-L14) will trigger a rebuild.

Resources

The docs workflow was cobbled together / inspired by a variety of resources:

lzachmann commented 2 years ago

Big lift has been made. Still need to find a Sphinx directive to parse docstrings in src/ directory for an "Internals" menu in the docs.

lzachmann commented 2 years ago

@vlandau I think napoleon may be the way to go? It allows for more natural docstring (e.g., Google or NumPy style) formatting. And napoleon actually comes with Sphinx now, so no need to pip install anything else. But we may need to make files in source modules, however....

https://sphinxcontrib-napoleon.readthedocs.io/en/latest/ https://gist.github.com/GLMeece/222624fc495caf6f3c010a8e26577d31

In our case, the docstrings from each submodule would be parsed using sphinx-apidoc -f -o source/ ../src.