Skip to main content

Generate Beautiful reStructuredText README.rst for GitHub, PyPi, GitLab, BitBucket

Project description

Sphinx README: Generate Beautiful reStructuredText README.rst for GitHub, PyPi, GitLab, BitBucket

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

Explore the docs »


PyPI Project for Sphinx README: Generate Beautiful reStructuredText README.rst for GitHub, PyPi, GitLab, BitBucket GitHub Repository for Sphinx README: Generate Beautiful reStructuredText README.rst for GitHub, PyPi, GitLab, BitBucket Downloads for Sphinx README Documentation for Sphinx README: Generate Beautiful reStructuredText README.rst for GitHub, PyPi, GitLab, BitBucket

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!


Demonstration of how reStructuredText README.rst files generated by Sphinx README render on GitHub, PyPi, GitLab, BitBucket

📋 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 or list of rst files to parse

Type: Union[str, List]

📢 Important

Filepaths should be specified relative to the source directory


readme_docs_url_type

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

Type: str

Must be either "code" or "html"

📝 Note

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

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

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

sphinx-readme-0.2.4.tar.gz (22.0 kB view details)

Uploaded Source

Built Distribution

sphinx_readme-0.2.4-py3-none-any.whl (23.0 kB view details)

Uploaded Python 3

File details

Details for the file sphinx-readme-0.2.4.tar.gz.

File metadata

  • Download URL: sphinx-readme-0.2.4.tar.gz
  • Upload date:
  • Size: 22.0 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/4.0.2 CPython/3.10.1

File hashes

Hashes for sphinx-readme-0.2.4.tar.gz
Algorithm Hash digest
SHA256 72a276555342be1402b6cd5ab87d8e7d8fb7a0a067506887c62f63f0c5a815b8
MD5 de0dd88c64fd82d3e1cf4d0d1ae8412b
BLAKE2b-256 0d6f26a3835ecc8d50c978bd45bf4d14f6719467eb32377d5eca1d5bfb930974

See more details on using hashes here.

File details

Details for the file sphinx_readme-0.2.4-py3-none-any.whl.

File metadata

File hashes

Hashes for sphinx_readme-0.2.4-py3-none-any.whl
Algorithm Hash digest
SHA256 79e27224db1f9bdd3d82995b1bfb2921bc4208e1ceeeb6522177cf50360ddb4b
MD5 22f0336031beab685b2fad64d0c0bb61
BLAKE2b-256 d93b3d7d79290a060ed26093aed673d21873de9f6ec84e5493f5f4e877e20e9d

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page