Sphinx README - Generate Beautiful README.rst for GitHub, PyPi, GitLab, BitBucket
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
Metadata
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 | Provenance | Actions |
|---|---|---|---|---|
| sphinx-readme-1.2.1.tar.gz | 27.5 kB | Without provenance | Details for sphinx-readme-1.2.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| sphinx_readme-1.2.1-py3-none-any.whl | Python 3 | none | any | Details for sphinx_readme-1.2.1-py3-none-any.whl |
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
|
Security for sphinx-readme 1.2.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.