Documentation is formatted in restructured text (ReST) and the website is built using Sphinx and some of its extensions. Specifically, the website is available for all our releases to allow users to check the documentation of the version of the package that they are using.
To contribute, make sure to install sphinx and its add-ons by running
python scripts/install_requirements.py --pinned False
in the repository root directory. You may also need to install Pandoc. You can contribute updates to existing documentation by navigating to the relevant part of the repository (typically in the docs directory), and editing the restructured text files (.rst) corresponding to your updates.
To build the webpage run the following command from the repository root directory:
python -m sphinx -v -b html -n -j auto docs docs/_build/html
or use the shortcut
This will generate the website in the directory mentioned at the end of the command. Rerunning this after making changes to individual files only rebuilds the changed pages, so the build time should be a lot shorter.
You can check that the document(s) render properly by inspecting the HTML with the following commands:
start docs/_build/html/index.html start docs/_build/html/quickstart.html ... start docs/_build/html/auto_examples/plot_*.html
The above code block works for Windows users. For MacOS users, use :code: open docs/_build/html/index.html For Linux users, use :code: xdg-open docs/_build/html/index.html
The rendered HTML files can be explored in any file explorer and then opened using a browser (e.g., Chrome/Firefox/Safari).
plot_* can be replaced with any of the notebooks in the
auto_examples folder. To view your changes, simply navigate to the
relevant part of the website and check that your updates render properly
and links work as expected.
Note that some changes to documentation may involve modifying several files (i.e: index files, other documents in which the current one should be linked). Be sure to modify all of the relevant documents and use the commands above to ensure that they all render properly.
If you encounter problems with the documentation build (locally or in your
pull request) and need help, simply @mention
@fairlearn/fairlearn-maintainers to get help.
Building the website for all versions¶
Our documentation build runs for each pull request and upon merging pull requests. There should not be a need to run this locally except for very rare cases.
To fully build the website for all versions use the following script:
python scripts/build_documentation.py --documentation-path=docs --output-path=docs/_build/html
or the shortcut
The comprehensive set of commands to build the website is in our CircleCI configuration file in the .circleci directory of the repository.