Generate Beautiful reStructuredText README.rst for GitHub, PyPi, GitLab, BitBucket
Project description
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
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
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"
"code": uses sphinx.ext.linkcode to replace references with links to highlighted source code
Example: parse_intersphinx_node()
"html": replaces references with links to HTML documentation entries
Example: parse_intersphinx_node()
📝 Note |
---|
If set to code, then
|
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 |
---|
If generating a README for a platform that doesn’t support raw directives (PyPi, GitLab, and BitBucket), be sure to disable readme_raw_directive:
|
Documentation
Full documentation can be found on ReadTheDocs
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for sphinx_readme-0.0.1b6-py3.10.egg
Algorithm | Hash digest | |
---|---|---|
SHA256 | ac7d5beabfa7bce3408bad8f7934595fcedc895aecac7871ef92a7db94ee4c24 |
|
MD5 | 2c3c572530b08da9075ff8493168c145 |
|
BLAKE2b-256 | 9d4d95b658cfd59ce37aab2616004c44f217e22157438eaa52c96a1be9e38f82 |