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.
Since plotting is an optional addition to Fairlearn, you may also need to install matplotlib
pip install matplotlib>=3.2.1
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:
Check if your required BibTex entry already exists in the docs/refs.bib file. If not, simply paste your entry at the end.
Change your bibtex id to the format
<author-last-name><4digit-year><keyword>
.Use the
:footcite:`bibtex-id`
role to create an inline citation rendered as[CitationNumber]
. For example,:footcite:`agarwal2018reductions`
will be rendered as [1].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].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: