A Sphinx extension to generate README.rst files that render beautifully on 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!
📋 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
|
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: |
📚 Documentation
Full documentation can be found on ReadTheDocs
1 maintainer
Metadata
1 maintainer
Release files for sphinx-readme 1.2.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| sphinx-readme-1.2.1.tar.gz | 27.5 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| sphinx_readme-1.2.1-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 55.6 kB
Release files / sphinx-readme-1.2.1.tar.gz
| Download URL | sphinx-readme-1.2.1.tar.gz |
|---|---|
| Size | 27.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
0629b48d5bcefb20b5b733b6a2961d712acf80ba034db6a8bc75aaa66432914d
|
|
BLAKE2b-256 checksum How to use checksums |
93f9376c6bea802b479092d6dd4a01535fac8a2ceac1dc54769062b022247222
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/4.0.2 CPython/3.10.1
|
Release files / sphinx_readme-1.2.1-py3-none-any.whl
| Download URL | sphinx_readme-1.2.1-py3-none-any.whl |
|---|---|
| Size | 28.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
94458b505ef1c8a0589431d097d225f2e6ab67785c04315d1870c4f537c766e4
|
|
BLAKE2b-256 checksum How to use checksums |
f6648aee4fc143888c3f46a43e0bb2cf7e089a7e02ca5ffa22cda1ff37848689
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/4.0.2 CPython/3.10.1
|
