Contributing documentation#

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

make doc

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

Note

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.

Note

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.

Citations#

Citations are built using the sphinxcontrib-bibtex extension. This allows us to use the refs.bib BibTeX file to generate our citations.

To add a citation:

  1. Check if your required BibTex entry already exists in the docs/refs.bib file. If not, simply paste your entry at the end.

  2. Change your bibtex id to the format <author-last-name><4digit-year><keyword>.

  3. Use the :footcite:`bibtex-id` role to create an inline citation rendered as [CitationNumber]. For example, :footcite:`agarwal2018reductions` will be rendered as 1.

  4. You can also use :footcite:t:`bibtex-id` to create a textual citation. The role :footcite:t:`agarwal2018reductions` will be rendered as Agarwal et al.1.

  5. To add the bibliography use .. footbibliography:: directive at the bottom of your file if not already present. This will list all the citations for the current document.

    For example .. footbibliography:: will be rendered as shown below:

    1(1,2)

    Alekh Agarwal, Alina Beygelzimer, Miroslav Dudík, John Langford, and Hanna M. Wallach. A reductions approach to fair classification. In ICML, volume 80 of Proceedings of Machine Learning Research, 60–69. PMLR, 2018. URL: http://proceedings.mlr.press/v80/agarwal18a.html.

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:

make doc

The comprehensive set of commands to build the website is in our CircleCI configuration file in the .circleci directory of the repository.