Contributing to Docs¶
Docs for various repos¶
Flyte is a large project and all the docs span multiple repositories. The core of the documention is in the flyteorg/flyte repository. Flyte uses Sphinx to compile it docs. Docs are automatically pushed on merge to master and docs are hosted using readthedocs.org
Sphinx and RST¶
Typically, we try to follow these characters in this order for heading separation.
# with overline * with overline = - ^
When Sphinx runs, an inventory file gets created and is available alongside each repo’s HTML pages. For example at
https://readthedocs.org/projects/flytecookbook/objects.inv. This file is a compressed inventory of all the sections, tags, etc. in the flyte cookbook documentation. This inventory file is what allows the intersphinx plugin to cross-link between projects.
There is an open-source tool called
sphobjinv that has managed to reverse engineer these files, and offers a CLI to help search for things inside them.
sphobjinv and simple usage
$ pip install sphobjinv # Using the CLI to query a hosted inventory file, note the -u switch $ sphobjinv suggest https://flytekit.readthedocs.io/en/latest/ -u task No inventory at provided URL. Attempting "https://flytekit.readthedocs.io/en/latest/objects.inv" ... Remote inventory found. :py:function:`flytekit.task` :std:doc:`tasks` :std:doc:`tasks.extend` :std:label:`tasks:tasks` # Using the CLI to query a local file, useful when iterating locally $ sphobjinv suggest ~/go/src/github.com/flyteorg/flytekit/docs/build/html/objects.inv task :py:function:`flytekit.task` :std:doc:`tasks` :std:doc:`tasks.extend` :std:label:`tasks:tasks`