Building README files into HTML docs#

Sometimes you want to include information in a README for those browsing the GitHub repo and the same information in the documentation for those browsing the HTML docs. To avoid duplicating the same information in two locations, you can pull README files into the docs as described below. We encourage you to use this judiciously as the README files must be readable in their raw format, preventing usage of Sphinx-specific semantic markup that enables better manageability of HTML docs.

If the myst_parser extension is enabled in conf.py, you can write the README in reStructuredText (.rst), or Markdown(.md). If you like, use the converter at https://cloudconvert.com/md-to-rst to easily convert Markdown to RST.

To pull in README content from outside the docs directory#

This is useful if you want to reuse content in a README at the root of the repo content describing the package or how to install it or multiple READMEs in different subdirectories of the code repo. The process is slightly different depending on if the README file is in RST or MD.

To use README.rst#

  1. Write the README files in reStructuredText (README.rst).

  2. In the docs/ directory, create a new RST file and add the following line to it:

    .. include:: ../path_to_README.rst

  3. List the file with the include directive in a Sphinx TOC in the docs structure.

  4. To include additional information in the HTML docs but not the README file, add that content to the RST file in the /docs folder after the include directive.

  5. To include information in the README but not the HTML docs, use the start_line, end_line, start_after, or end_before options with the include directive to select what content from the README should be included in the HTML. For more information, see https://docutils.sourceforge.io/docs/ref/rst/directives.html#include.

To use README.md#

  1. Write the README files in Markdown (README.md).

  2. In the docs/ directory, create a new RST file and add the following lines to it:

    .. include:: ../path_to_README.rst
   :parser: myst_parser.sphinx_

  3. List the file with the include directive in a Sphinx TOC in the docs structure.

  4. If there are any image files in README.md, they must be commented out as below:

    [//]: #![image-display-name](image-filename.png)

Warning

The connection between the README and HTML docs isn’t apparent from the README, so when content changes in the README, the content in the HTML can be changed in inadvertent ways. Use this cautiously!

To include a docs/README file in the HTML#

You may want to include a README file in the docs directory for those browsing the code and also build it into the HTML documentation.

If the myst_parser is enabled in conf.py, add a README.rst or README.md file under docs/, and list the README file in a Sphinx TOC. If the myst_parser is not enabled, the README file must be in reStructuredText.

To exclude a docs/README file in the HTML#

More likely, you will want to include a README in the docs directory that contains some information about how the docs are built, what the contribution model is, or similar that is not included in the built HTML.

There are two options to exclude that README file from being built into the HTML.

  • Disable myst_parser in conf.py and write the README file in Markdown. Sphinx will include only RST files under docs/ in the build.

  • Enable myst_parser in conf.py and write the README file in Markdown or RST. List the file you want to exclude from the HTML build in exclude_patterns in conf.py.