{"id":19943739,"url":"https://github.com/tdkorn/sphinx-readme","last_synced_at":"2025-05-03T15:33:12.081Z","repository":{"id":179407525,"uuid":"641559284","full_name":"TDKorn/sphinx-readme","owner":"TDKorn","description":"Generate Beautiful reStructuredText README.rst for GitHub, PyPi, GitLab, BitBucket","archived":false,"fork":false,"pushed_at":"2024-03-30T04:21:28.000Z","size":11471,"stargazers_count":7,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-18T18:10:21.600Z","etag":null,"topics":["docutils","readme","restructuredtext","rst","sphinx","sphinx-extension"],"latest_commit_sha":null,"homepage":"https://sphinx-readme.readthedocs.io","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/TDKorn.png","metadata":{"files":{"readme":"README.rst","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2023-05-16T18:16:27.000Z","updated_at":"2025-01-09T20:02:23.000Z","dependencies_parsed_at":null,"dependency_job_id":"bf2e9485-cb97-40cd-b362-fd62f1528bc0","html_url":"https://github.com/TDKorn/sphinx-readme","commit_stats":null,"previous_names":["tdkorn/sphinx-readme"],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TDKorn%2Fsphinx-readme","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TDKorn%2Fsphinx-readme/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TDKorn%2Fsphinx-readme/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TDKorn%2Fsphinx-readme/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/TDKorn","download_url":"https://codeload.github.com/TDKorn/sphinx-readme/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252211838,"owners_count":21712476,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docutils","readme","restructuredtext","rst","sphinx","sphinx-extension"],"created_at":"2024-11-13T00:17:50.482Z","updated_at":"2025-05-03T15:33:10.259Z","avatar_url":"https://github.com/TDKorn.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":".. |.configuration/configuring| replace:: Extension Configuration\n.. _.configuration/configuring: https://sphinx-readme.readthedocs.io/en/latest/configuration/configuring.html\n.. |.html_baseurl| replace:: ``html_baseurl``\n.. _.html_baseurl: https://sphinx-readme.readthedocs.io/en/latest/configuration/configuring.html#confval-html_baseurl\n.. |.html_context| replace:: ``html_context``\n.. _.html_context: https://sphinx-readme.readthedocs.io/en/latest/configuration/configuring.html#confval-html_context\n.. |.~.parse_intersphinx_nodes| replace:: ``parse_intersphinx_nodes()``\n.. _.~.parse_intersphinx_nodes: https://github.com/TDKorn/sphinx-readme/blob/v1.2.1/sphinx_readme/parser.py#L256-L293\n.. |.read the docs user documentation+guides/edit-source-links-sphinx-colon-github+HTML Context Settings| replace:: HTML Context Settings\n.. _.read the docs user documentation+guides/edit-source-links-sphinx-colon-github+HTML Context Settings: https://docs.readthedocs.io/en/stable/guides/edit-source-links-sphinx.html#github\n.. |.readme_docs_url_type| replace:: ``readme_docs_url_type``\n.. _.readme_docs_url_type: https://sphinx-readme.readthedocs.io/en/latest/configuration/configuring.html#confval-readme_docs_url_type\n.. |.readme_inline_markup| replace:: ``readme_inline_markup``\n.. _.readme_inline_markup: https://sphinx-readme.readthedocs.io/en/latest/configuration/configuring.html#confval-readme_inline_markup\n.. |.readme_out_dir+output directory| replace:: ``output directory``\n.. _.readme_out_dir+output directory: https://sphinx-readme.readthedocs.io/en/latest/configuration/configuring.html#confval-readme_out_dir\n.. |.readme_raw_directive| replace:: ``readme_raw_directive``\n.. _.readme_raw_directive: https://sphinx-readme.readthedocs.io/en/latest/configuration/configuring.html#confval-readme_raw_directive\n.. |.readme_replace_attrs| replace:: ``readme_replace_attrs``\n.. _.readme_replace_attrs: https://sphinx-readme.readthedocs.io/en/latest/configuration/configuring.html#confval-readme_replace_attrs\n.. |.readme_src_files| replace:: ``readme_src_files``\n.. _.readme_src_files: https://sphinx-readme.readthedocs.io/en/latest/configuration/configuring.html#confval-readme_src_files\n.. |.sphinx+html_baseurl| replace:: ``html_baseurl``\n.. _.sphinx+html_baseurl: https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_baseurl\n.. |.sphinx+html_context| replace:: ``html_context``\n.. _.sphinx+html_context: https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_context\n.. |.sphinx+usage/domains/restructuredtext+reStructuredText Domain| replace:: reStructuredText Domain\n.. _.sphinx+usage/domains/restructuredtext+reStructuredText Domain: https://www.sphinx-doc.org/en/master/usage/domains/restructuredtext.html\n.. |.sphinx+usage/domains/standard+Standard Domain| replace:: Standard Domain\n.. _.sphinx+usage/domains/standard+Standard Domain: https://www.sphinx-doc.org/en/master/usage/domains/standard.html\n.. |.~.sphinx.domains.python.PythonDomain| replace:: ``PythonDomain``\n.. _.~.sphinx.domains.python.PythonDomain: https://www.sphinx-doc.org/en/master/extdev/domainapi.html#sphinx.domains.python.PythonDomain\n.. |.~.sphinx.environment.BuildEnvironment| replace:: ``BuildEnvironment``\n.. _.~.sphinx.environment.BuildEnvironment: https://www.sphinx-doc.org/en/master/extdev/envapi.html#sphinx.environment.BuildEnvironment\n.. |.sphinx.ext.autodoc| replace:: ``sphinx.ext.autodoc``\n.. _.sphinx.ext.autodoc: https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#module-sphinx.ext.autodoc\n.. |.~.sphinx.ext.autodoc| replace:: ``autodoc``\n.. _.~.sphinx.ext.autodoc: https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#module-sphinx.ext.autodoc\n.. |.sphinx.ext.linkcode| replace:: ``sphinx.ext.linkcode``\n.. _.sphinx.ext.linkcode: https://www.sphinx-doc.org/en/master/usage/extensions/linkcode.html#module-sphinx.ext.linkcode\n\n\n\n.. role:: rst(code)\n   :class: highlight\n\n.. |env| replace:: |.~.sphinx.environment.BuildEnvironment|_\n.. |py_domain| replace:: |.~.sphinx.domains.python.PythonDomain|_\n.. |std_domain| replace:: |.sphinx+usage/domains/standard+Standard Domain|_\n.. |rst_domain| replace:: |.sphinx+usage/domains/restructuredtext+reStructuredText Domain|_\n\n.. meta::\n   :author: Adam Korn\n   :title: Sphinx README - Generate README.rst That Renders Beautifully on GitHub, PyPi, GitLab, BitBucket\n   :description: Sphinx extension to generate reStructuredText README.rst files that render beautifully on GitHub, PyPi, GitLab, BitBucket\n\n\n\n.. raw:: html\n\n   \u003cdiv align=\"center\"\u003e\n\n.. image:: https://raw.githubusercontent.com/TDKorn/sphinx-readme/v1.2.1/docs/source/_static/logo_readme.png\n   :alt: Sphinx README: Generate Beautiful reStructuredText README.rst for GitHub, PyPi, GitLab, BitBucket\n   :align: center\n   :width: 25%\n\n\n\n.. raw:: html\n\n   \u003ch1\u003eSphinx README\u003c/h1\u003e\n\n\n\n\n\nA Sphinx extension to generate ``README.rst`` files that render beautifully on GitHub, PyPi, GitLab, BitBucket\n\n.. |RTD| replace:: **Explore the docs »**\n.. _RTD: https://sphinx-readme.readthedocs.io/en/latest/\n\n|RTD|_\n\n\n\n.. image:: https://img.shields.io/pypi/v/sphinx-readme?color=eb5202\n   :target: https://pypi.org/project/sphinx-readme\n   :alt: PyPI Project for Sphinx README: Generate Beautiful reStructuredText README.rst for GitHub, PyPi, GitLab, BitBucket\n\n.. image:: https://img.shields.io/badge/GitHub-sphinx--readme-4f1abc\n   :target: https://github.com/tdkorn/sphinx-readme\n   :alt: GitHub Repository for Sphinx README: Generate Beautiful reStructuredText README.rst for GitHub, PyPi, GitLab, BitBucket\n\n.. image:: https://static.pepy.tech/personalized-badge/sphinx-readme?period=total\u0026units=none\u0026left_color=grey\u0026right_color=blue\u0026left_text=Downloads\n   :target: https://pepy.tech/project/sphinx-readme\n   :alt: Downloads for Sphinx README\n\n.. image:: https://readthedocs.org/projects/sphinx-readme/badge/?version=latest\n   :target: https://sphinx-readme.readthedocs.io/en/latest/?badge=latest\n   :alt: Documentation for Sphinx README: Generate Beautiful reStructuredText README.rst for GitHub, PyPi, GitLab, BitBucket\n\n.. image:: https://img.shields.io/github/actions/workflow/status/TDKorn/sphinx-readme/tests.yml?label=build\u0026color=33ce57\n   :target: https://github.com/TDKorn/sphinx-readme/actions/workflows/tests.yml\n   :alt: Build Status\n\n.. image:: https://codecov.io/gh/TDKorn/sphinx-readme/graph/badge.svg?token=RZCUCGIU0Q\n   :target: https://codecov.io/gh/TDKorn/sphinx-readme\n   :alt: Code Coverage\n\n.. raw:: html\n\n   \u003c/div\u003e\n\n|\n\nAbout Sphinx README\n~~~~~~~~~~~~~~~~~~~~~~~\n\n\n.. raw:: html\n\n   \u003ctable\u003e\n       \u003ctr align=\"left\"\u003e\n           \u003cth\u003e\n\n📚 What's Sphinx README?\n\n.. raw:: html\n\n   \u003c/th\u003e\n   \u003ctr\u003e\u003ctd\u003e\n\n``sphinx_readme`` is a ``reStructuredText`` parser that uses Sphinx\nto generate ``rst`` files that render beautifully on\nGitHub, PyPi, GitLab, and BitBucket.\n\n.. raw:: html\n\n   \u003c/td\u003e\u003c/tr\u003e\n   \u003c/table\u003e\n\n\n\n**With** ``sphinx_readme`` **, there's no need to rewrite your** ``README.rst`` **as a** ``README.md`` **file**\n\nFiles generated by ``sphinx_readme`` have nearly identical appearance and functionality\nas ``html`` builds, including |.sphinx.ext.autodoc|_ cross-references!\n\n\n\n.. image:: https://raw.githubusercontent.com/TDKorn/sphinx-readme/v1.2.1/docs/source/_static/demo/demo.gif\n   :alt: Demonstration of how reStructuredText README.rst files generated by Sphinx README render on GitHub, PyPi, GitLab, BitBucket\n   :width: 75%\n\n\n📋 Features\n~~~~~~~~~~~~\n\n``sphinx_readme`` adds support for the following ``sphinx`` and ``docutils`` directives and features:\n\n* |.sphinx.ext.autodoc|_ cross-references (``:mod:``, ``:class:``, ``:meth:``, ``:func:``, and ``:attr:``)\n* Standard cross-reference roles (``:doc:`` and ``:ref:``)\n* Generic and Specific Admonitions\n* Only directives\n* Toctrees\n* Rubrics\n* Images\n\n\n⚙ Installation\n~~~~~~~~~~~~~~~~\n\nInstall using pip::\n\n   pip install sphinx-readme\n\n\nAdd the extension to your ``conf.py``:\n\n.. code-block:: python\n\n   extensions = [\n      'sphinx_readme',\n   ]\n\n\n\n🔧 Configuration\n~~~~~~~~~~~~~~~~~\n\n\n\n\nPlease see |.configuration/configuring|_ for full documentation on configuration variables\n\n\nMandatory ``conf.py`` Values\n==================================\n\n|.html_context|_\n A dictionary containing info about your repository (|.sphinx+html_context|_)\n\n  **Type:** ``dict``\n\n * At minimum, the username and repository name must be specified\n * Please see |.read the docs user documentation+guides/edit-source-links-sphinx-colon-github+HTML Context Settings|_\n   to determine the correct dictionary keys for your hosting platform\n\n\n|\n\n|.html_baseurl|_\n The base URL which points to the root of the HTML documentation (|.sphinx+html_baseurl|_)\n\n  **Type:** ``str``\n\n\n|\n\n|.readme_src_files|_\n An individual/list of ``rst`` source files to parse, or a dictionary of source files mapped to output files\n\n  **Type:** ``Union[str, List[str], Dict[str,str]]``\n\n\n.. raw:: html\n\n   \u003ctable\u003e\n       \u003ctr align=\"left\"\u003e\n           \u003cth\u003e\n\n📢 Important\n\n.. raw:: html\n\n   \u003c/th\u003e\n   \u003ctr\u003e\u003ctd\u003e\n\nFilepaths should be specified relative to the source directory\nand |.readme_out_dir+output directory|_\n\n.. raw:: html\n\n   \u003c/td\u003e\u003c/tr\u003e\n   \u003c/table\u003e\n\n\n|\n\n|.readme_docs_url_type|_\n The documentation source to link to when resolving |.~.sphinx.ext.autodoc|_ cross-references\n\n  **Type:** ``str``\n\n Must be either ``\"code\"`` or ``\"html\"``\n\n * ``\"code\"``: uses |.sphinx.ext.linkcode|_ to replace references with links to highlighted source code\n\n   **Example**: |.~.parse_intersphinx_nodes|_\n\n\n * ``\"html\"``: replaces references with links to HTML documentation entries\n\n   **Example**: |parse_intersphinx_nodes_html|_\n\n\n.. raw:: html\n\n   \u003ctable\u003e\n       \u003ctr align=\"left\"\u003e\n           \u003cth\u003e\n\n📝 Note\n\n.. raw:: html\n\n   \u003c/th\u003e\n   \u003ctr\u003e\u003ctd\u003e\n\nIf set to ``code``, non-external :code:`:attr:` cross-references will not be replaced with links\n\n* Instead, they'll be replaced with ``inline literals`` or left as is\n* Please see |.readme_replace_attrs|_ and |.readme_inline_markup|_\n\n.. raw:: html\n\n   \u003c/td\u003e\u003c/tr\u003e\n   \u003c/table\u003e\n\n\n\n.. |parse_intersphinx_nodes_html| replace:: ``parse_intersphinx_nodes()``\n.. _parse_intersphinx_nodes_html: http://sphinx-readme.readthedocs.io/en/latest/parser.html#sphinx_readme.parser.READMEParser.parse_intersphinx_nodes\n\n\nSample ``conf.py``\n~~~~~~~~~~~~~~~~~~~\n\n.. code-block:: python\n\n   extensions = [\n      \"sphinx_readme\",\n   ]\n\n   html_context = {\n      'display_github': True,\n      'github_user': 'TDKorn',\n      'github_repo': 'sphinx-readme',\n   }\n\n   html_baseurl = \"https://sphinx-readme.readthedocs.io/en/latest\"\n\n   readme_src_files = \"README.rst\"\n\n   readme_docs_url_type = \"code\"\n\n\n\n\n.. raw:: html\n\n   \u003ctable\u003e\n       \u003ctr align=\"left\"\u003e\n           \u003cth\u003e\n\n📢 Important\n\n.. raw:: html\n\n   \u003c/th\u003e\n   \u003ctr\u003e\u003ctd\u003e\n\nFor platforms that don't support the ``raw`` directive (PyPi, GitLab, and BitBucket),\nbe sure to disable |.readme_raw_directive|_:\n\n.. code-block:: python\n\n   readme_raw_directive = False\n\n.. raw:: html\n\n   \u003c/td\u003e\u003c/tr\u003e\n   \u003c/table\u003e\n\n\n\n\n📚 Documentation\n~~~~~~~~~~~~~~~~\n\nFull documentation can be found on |docs|_\n\n\n.. |docs| replace:: ``ReadTheDocs``\n.. _docs: https://sphinx-readme.readthedocs.io/en/latest\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftdkorn%2Fsphinx-readme","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftdkorn%2Fsphinx-readme","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftdkorn%2Fsphinx-readme/lists"}