Sphinx README

A Sphinx extension to generate README.rst files that render beautifully on GitHub, PyPi, GitLab, BitBucket

Explore the docs »_

About Sphinx README

📚 What's Sphinx README?
sphinx_readme is a reStructuredText parser that uses Sphinx to generate rst files that render beautifully on GitHub, PyPi, GitLab, and BitBucket.

With sphinx_readme , there's no need to rewrite your README.rst as a README.md file

Files generated by sphinx_readme have nearly identical appearance and functionality as html builds, including sphinx.ext.autodoc_ cross-references!

📋 Features

sphinx_readme adds support for the following sphinx and docutils directives and features:

• sphinx.ext.autodoc_ cross-references (:mod:, :class:, :meth:, :func:, and :attr:)
• Standard cross-reference roles (:doc: and :ref:)
• Generic and Specific Admonitions
• Only directives
• Toctrees
• Rubrics
• Images

⚙ Installation

Install using pip:

pip install sphinx-readme

Add the extension to your conf.py:

extensions = [
   'sphinx_readme',
]

🔧 Configuration

Please see Extension Configuration_ for full documentation on configuration variables

Mandatory conf.py Values

html_context_

A dictionary containing info about your repository (html_context_)

Type: dict

• At minimum, the username and repository name must be specified
• Please see HTML Context Settings_ to determine the correct dictionary keys for your hosting platform

html_baseurl_

The base URL which points to the root of the HTML documentation (html_baseurl_)

Type: str

readme_src_files_

An individual/list of rst source files to parse, or a dictionary of source files mapped to output files

Type: Union[str, List[str], Dict[str,str]]

📢 Important
Filepaths should be specified relative to the source directory and output directory_

readme_docs_url_type_

The documentation source to link to when resolving autodoc_ cross-references

Type: str

Must be either "code" or "html"

• "code": uses sphinx.ext.linkcode_ to replace references with links to highlighted source code

  Example: parse_intersphinx_nodes()_

• "html": replaces references with links to HTML documentation entries

  Example: parse_intersphinx_nodes()_

📝 Note
If set to code, non-external :attr: cross-references will not be replaced with links Instead, they'll be replaced with inline literals or left as is Please see readme_replace_attrs_ and readme_inline_markup_

Sample conf.py

extensions = [
   "sphinx_readme",
]

html_context = {
   'display_github': True,
   'github_user': 'TDKorn',
   'github_repo': 'sphinx-readme',
}

html_baseurl = "https://sphinx-readme.readthedocs.io/en/latest"

readme_src_files = "README.rst"

readme_docs_url_type = "code"

📢 Important
For platforms that don't support the raw directive (PyPi, GitLab, and BitBucket), be sure to disable readme_raw_directive_: readme_raw_directive = False

📚 Documentation

Full documentation can be found on ReadTheDocs_