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

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

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 Build Status Code Coverage

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