As a prerequisite, a RAPIDS compatible GPU is required to build the docs since the notebooks in the docs execute the code to generate the HTML output.
In order to build the docs, we need the conda dev environment from cudf and build cudf from source. See build instructions.
-
Create a conda env with the dependencies to build the deployment docs from source.
conda env create -f conda/environments/deployment_docs_cuda11.5.yml
-
Once the conda environment is built, run the following
make html
This should run Sphinx in your shell, and outputs to build/html/index.html.
When developing docs locally it can be nice to view them in your browser and have changes reflected immediately. You can do this with sphinx-autobuild. This tool will build your docs as above but will also host them on a local web server. It will watch for file changes, rebuild automatically and tell the browser page to reload. Magic!
$ sphinx-autobuild source build/html
[sphinx-autobuild] > sphinx-build ./source ./build/html
Running Sphinx v4.5.0
...
build succeeded.
The HTML pages are in build.
[I 220413 12:13:40 server:335] Serving on http://127.0.0.1:8000This project uses prettier and markdownlint to enforce automatic formatting and consistent style as well as identify rendering issues early.
It is recommended to run this automatically on each commit using pre-commit as linting rules are enforced via CI checks and linting locally will save time in code review.
$ pre-commit install
pre-commit installed at .git/hooks/pre-commit
$ git commit -am "My awesome commit"
prettier.................................................................Passed
markdownlint.............................................................Passed