Updating documentation#
What is good documentation?#
Good Documentation
Always refers to the enduser. Do not document why something is the way it is, but rather how to use it.
Doesn’t lie and is always up-to-ate. Whenever code is updated, consider if the documentation needs to change accordingly to reflect reality.
Provides useful links whenever usable. Do not reference another object without linking it.
Tutorials#
All tutorials are markdown files stored at the tutorial folder.
When adding a new tutorial, you must add its name to the index.rst
file in the respective folder.
We are using the MyST parser which adds
some additional syntax over markdown.
A tutorial should always be easy to understand, and reference api documentation for future readings.
Note
You can reference symbols by defining links
e.g.: [`flair.set_seed`](#flair.set_seed)
for a function
e.g.: [entity-linking](project:../tutorial/tutorial-basics/entity-linking.md)
for another tutorial
Docstrings#
For docstrings we follow the Google docstring format. We do not need to specify types or default values, as those will be extracted from the function signature.
Docstrings have usual a 1 liner giving a simple explanation of the object. Then there is a more detailed explanation followed if required.
Ensure that you always use cross-references instead of just mentioning another object,
e.g. :class:`flair.models.SequenceTagger`
can be used to reference the SequenceTagger.
Building the local docs#
For building the docs,
Ensure that you have everything committed. Local changes won’t be used for building.
Install the build dependencies via
pip install -r docs/requirements.txt
.In
docs/conf.py
temporarily add your local branch name to thesmv_branch_whitelist
pattern. E.g. if your branch is calleddoc-page
smv_branch_whitelist
need to have the valuer"^master|doc-page$"
run
sphinx-multiversion docs doc_build/
to generate the docs.open
doc_build/<your branch name>/index.html
to view the docs.