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

Sphinx and RST



Typically, we try to follow these characters in this order for heading separation.

# with overline
* with overline


Intersphinx is a plugin that all Flyte repos that build Sphinx documentation use for cross-referencing with each other. There’s some good background information on it on these slides.

Inventory File

When Sphinx runs, an inventory file gets created and is available alongside each repo’s HTML pages. For example at 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.


Installing sphobjinv and simple usage

$ pip install sphobjinv

# Using the CLI to query a hosted inventory file, note the -u switch
$ sphobjinv suggest -u task

No inventory at provided URL.
Attempting "" ...
Remote inventory found.


# Using the CLI to query a local file, useful when iterating locally
$ sphobjinv suggest ~/go/src/ task



Even though the sphobjinv CLI returns :py:function:..., when actually creating a link you should just use :py:func:.... See this. Here is a quick list of mappings

Conversion table for - sphobjinv

What the tool returns?

What you should use instead?









Linking Examples

In the file of each repo, there is an intersphinx mapping argument that looks something like this

intersphinx_mapping = {
    "python": ("", None),
    "flytekit": ("", None),

This file is what tells the plugin where to look for these inventory files, and what project name to refer to each inventory file as. The project name is important because they’re used when actually referencing something from the inventory.

Here are some examples, first the code and then the link

Task: :std:doc:`generated/flytekit.task`

Task: flytekit.task

:std:doc:`Using custom words <generated/flytekit.task>`

Using custom words


Linking to Python elements changes based on what you’re linking to. Check out this section. For instance linking to the task decorator in flytekit uses the func role.

Link to flytekit code :py:func:`flytekit:flytekit.task`

Link to flytekit code flytekit.task()

Other elements use different Sphinx roles, here are some examples using Python core docs.

:py:mod:`Module <python:typing>`
:py:class:`Class <python:typing.Type>`
:py:data:`Data <python:typing.Callable>`
:py:func:`Function <python:typing.cast>`
:py:meth:`Method <python:pprint.PrettyPrinter.format>`