Extension Configuration

Install using pip:

pip install sphinx-readme

Add the extension to your conf.py:

extensions = [
   "sphinx_readme",
]

For an example of the minimum required configuration, please see the sample conf.py file

Mandatory conf.py values

html_context

html_context

A dictionary containing info about your repository (html_context)

  • 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

Type

Dict

html_baseurl

html_baseurl

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

Type

str

readme_src_files

readme_src_files

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

Important

Filepaths should be specified relative to the source directory and output directory

Type

Union[str, List]

readme_docs_url_type

readme_docs_url_type

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

Must be either "code" or "html"

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

Note

If set to code, non-external :attr: cross-references will not be replaced with links

Optional conf.py values

readme_out_dir

readme_out_dir

Specifies the path of the directory to save generated rst files to

The value should be provided as either

  1. An absolute path; or

  2. A path relative to the source directory

Type

Union[str, Path]

Default

the root directory of your repository, via get_repo_dir()

readme_replace_attrs

readme_replace_attrs

Specifies if non-external attribute (:attr:) cross-references should be replaced

…

If True, the value of readme_docs_url_type determines how replacements are made:

  • "html": references are replaced with a link to the corresponding documentation entry

Example

:attr:`icon_map` would be replaced with icon_map or icon_map, depending on the value of readme_inline_markup

  • "code": attributes are replaced with inline markup

Example

:attr:`icon_map` would be replaced with icon_map

Note

External attribute cross-references are always replaced with links to documentation

Type

bool

Default

True

readme_inline_markup

readme_inline_markup

Specifies if replacements for cross-references should use inline markup

  • If True, the substitution for :attr:`icon_map` would be icon_map

  • If False, the substitution for :attr:`icon_map` would be icon_map

Type

bool

Default

True

readme_raw_directive

readme_raw_directive

Specifies if the raw directive is supported by the platform you intend to render the generated file on

Tip

  • GitHub supports the raw directive

  • PyPi, GitLab, and BitBucket do not support the raw directive

If set to False,

  • Admonitions will be replaced with the list-table directive instead of HTML tables

  • All raw directives in the file will be removed

Type

bool

Default

True

readme_tags

readme_tags

Specifies tags to use when evaluating the <expression> argument of only directives

Tip

See replace_only_directives() for more detail

Type

List[str]

Default

["readme"]

readme_include_directive

readme_include_directive

Specifies if include directives should be parsed (file content inserted) or removed

Type

bool

Default

True

readme_admonition_icons

readme_admonition_icons

An optional mapping of admonition classes and their icons

  • If specified, will be used to update the icon_map (below)

Type

Optional[Dict[str, str]]

Default

{
 'attention': 'πŸ””οΈ',
 'caution': '⚠️',
 'danger': '☒',
 'error': 'β›”',
 'hint': '🧠',
 'important': 'πŸ“’',
 'note': 'πŸ“',
 'tip': 'πŸ’‘',
 'warning': '🚩',
 'default': 'πŸ“„'
}

readme_default_admonition_icon

readme_default_admonition_icon

The icon to use when a generic admonition either

  • Has no class

  • Uses a class that has no corresponding icon in the icon_map

Type

str

Default

"πŸ“„"

readme_rubric_heading

readme_rubric_heading

The character to use when replacing rubric directives with section headers

Must be one of the following valid section title adornment characters:

! " # $ % & ' ( ) * + , - . / : ; < = > ? @ [ \ ] ^ _ ` { | } ~

If not specified, rubrics will be replaced with bold text instead of a heading

Type

str

Default

bold inline markup (**title**)

readme_blob

readme_blob

The repository blob to link to - any of "head", "last_tag", or "{blob}"

  • "head": links to the most recent commit hash; if this commit is tagged, uses the tag instead

  • "last_tag": links to the most recently tagged commit; if no tags exist, uses "head"

  • "{blob}": links to the specified blob, for example "master" or "v2.0.1"

Type

str

Default

"head"

linkcode_resolve

linkcode_resolve

A linkcode_resolve() function for sphinx.ext.linkcode to use when resolving the target of autodoc cross-references

Type

Callable

Default

return value of get_linkcode_resolve()