diff --git a/README.rst b/README.rst index ca0d2a0..6366329 100644 --- a/README.rst +++ b/README.rst @@ -1,3 +1,22 @@ +.. |.~.get_linkcode_resolve| replace:: ``get_linkcode_resolve()`` +.. _.~.get_linkcode_resolve: https://sphinx-github-style.readthedocs.io/en/latest/modules.html#sphinx_github_style.__init__.get_linkcode_resolve +.. |linkcode_blob| replace:: ``linkcode_blob`` +.. _linkcode_blob: https://sphinx-github-style.readthedocs.io/en/latest/index.html#confval-linkcode_blob +.. |linkcode_link_text| replace:: ``linkcode_link_text`` +.. _linkcode_link_text: https://sphinx-github-style.readthedocs.io/en/latest/index.html#confval-linkcode_link_text +.. |linkcode_resolve| replace:: ``linkcode_resolve`` +.. _linkcode_resolve: https://sphinx-github-style.readthedocs.io/en/latest/index.html#confval-linkcode_resolve +.. |linkcode_url| replace:: ``linkcode_url`` +.. _linkcode_url: https://sphinx-github-style.readthedocs.io/en/latest/index.html#confval-linkcode_url +.. |sphinx+html_context| replace:: ``html_context`` +.. _sphinx+html_context: https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_context +.. |.sphinx.ext.linkcode| replace:: ``sphinx.ext.linkcode`` +.. _.sphinx.ext.linkcode: https://www.sphinx-doc.org/en/master/usage/extensions/linkcode.html#module-sphinx.ext.linkcode +.. |.sphinx.ext.viewcode| replace:: ``sphinx.ext.viewcode`` +.. _.sphinx.ext.viewcode: https://www.sphinx-doc.org/en/master/usage/extensions/viewcode.html#module-sphinx.ext.viewcode +.. |top_level| replace:: ``top_level`` +.. _top_level: https://sphinx-github-style.readthedocs.io/en/latest/index.html#confval-top_level + .. Title: Sphinx Github Style .. Description: A Sphinx extension to add GitHub source code links and syntax highlighting .. Author: TDKorn (Adam Korn) @@ -5,21 +24,13 @@ .. meta:: :title: Sphinx Github Style :description: A Sphinx extension to add GitHub source code links and syntax highlighting - -.. |.get_linkcode_resolve| replace:: ``get_linkcode_resolve()`` -.. _.get_linkcode_resolve: https://github.com/TDKorn/sphinx-github-style/blob/v1.0.5/sphinx_github_style/__init__.py#L148-L214 -.. |.add_linkcode_node_class| replace:: ``add_linkcode_node_class()`` -.. _.add_linkcode_node_class: https://github.com/TDKorn/sphinx-github-style/blob/v1.0.5/sphinx_github_style/add_linkcode_class.py#L9-L24 -.. |.TDKStyle| replace:: ``TDKStyle`` -.. _.TDKStyle: https://github.com/TDKorn/sphinx-github-style/blob/v1.0.5/sphinx_github_style/github_style.py#L44-L139 -.. |.TDKMethLexer| replace:: ``TDKMethLexer`` -.. _.TDKMethLexer: https://github.com/TDKorn/sphinx-github-style/blob/v1.0.5/sphinx_github_style/meth_lexer.py#L27-L42 + + .. |.github_style| replace:: ``github_style.css`` -.. _.github_style: https://github.com/tdkorn/sphinx-github-style/blob/v1.0.5/sphinx_github_style/_static/github_style.css -.. |RTD| replace:: ReadTheDocs -.. _RTD: https://sphinx-github-style.readthedocs.io/en/latest/ -.. |docs| replace:: **Explore the docs ยป** -.. _docs: https://sphinx-github-style.readthedocs.io/en/latest/ +.. _.github_style: https://github.com/tdkorn/sphinx-github-style/tree/v1.0.4/sphinx_github_style/_static/github_style.css + + + .. raw:: html @@ -27,18 +38,28 @@
-.. image:: docs/source/_static/logo_square_grey_blue.png +.. image:: https://raw.githubusercontent.com/TDKorn/sphinx-github-style/master/docs/source/_static/logo_square_grey_blue.png :alt: Sphinx GitHub Style: GitHub Integration and Pygments Style for Sphinx Documentation :width: 25% + + .. raw:: html

Sphinx Github Style

-GitHub source code links and syntax highlighting for Sphinx docs + +GitHub source code links and syntax highlighting for Sphinx documentation + + +.. |docs| replace:: **Explore the docs ยป** +.. _docs: https://sphinx-github-style.readthedocs.io/en/latest/ |docs|_ + + + .. image:: https://img.shields.io/pypi/v/sphinx-github-style?color=eb5202 :target: https://pypi.org/project/sphinx-github-style/ :alt: PyPI Version @@ -61,44 +82,54 @@ GitHub source code links and syntax highlighting for Sphinx docs
+ About ~~~~~~~~~~~~~ -``sphinx-github-style`` is a Sphinx extension that makes your docs look like and link to GitHub +``sphinx-github-style`` is a Sphinx extension that links your documentation to GitHub source code. +It also adds syntax highlighting for code blocks similar to GitHub's pretty lights dark theme. ... + GitHub Source Code Links =============================== -.. |linkcode| replace:: ``sphinx.ext.linkcode`` -.. _linkcode: https://www.sphinx-doc.org/en/master/usage/extensions/linkcode.html -**Using** |linkcode|_, a ``View on GitHub`` **link is added to the documentation of every class, method and function:** +Using |.sphinx.ext.linkcode|_, a ``View on GitHub`` link is added to the documentation of every class, method, function, and property: -.. image:: https://user-images.githubusercontent.com/96394652/220941352-f5530a56-d338-4b90-b83a-4b22b0f632fe.png - :alt: sphinx github style adds a "View on GitHub" link -**They link to and highlight the corresponding code block in your GitHub repo:** -.. image:: https://user-images.githubusercontent.com/96394652/220945912-447173db-2ac7-4e00-bec5-3859753bf687.png -| +.. image:: https://raw.githubusercontent.com/TDKorn/sphinx-github-style/master/docs/source/_static/github_link.png + :alt: sphinx-github-style adds a "View on GitHub" link + + +They link to and highlight the corresponding code block in your GitHub repository: + + + +.. image:: https://raw.githubusercontent.com/TDKorn/sphinx-github-style/master/docs/source/_static/github_linked_code.png + :alt: The linked corresponding highlighted source code block on GitHub + + .. raw:: html - - - - - + +
๐Ÿ“ Note
+
-These links can be used with/instead of the links added by ``sphinx.ext.viewcode`` +๐Ÿ“ Note -* They use a newly added ``linkcode-link`` class which can be styled using CSS +.. raw:: html + +
+These links can be `styled with CSS `_ and used with/instead +of the links added by |.sphinx.ext.viewcode|_ .. raw:: html @@ -106,18 +137,18 @@ These links can be used with/instead of the links added by ``sphinx.ext.viewcode
-| Syntax Highlighting ==================== -``sphinx-github-style`` **also contains a** ``Pygments`` **style to highlight code in your documentation similar to GitHub:** +``sphinx-github-style`` also contains a ``Pygments`` style to highlight code blocks similar to GitHub: -.. image:: https://user-images.githubusercontent.com/96394652/220946796-bf7aa236-964d-48e7-83e2-142aac00b0dd.png + +.. image:: https://raw.githubusercontent.com/TDKorn/sphinx-github-style/master/docs/source/_static/syntax_highlighting.png + :alt: A code block highlighted by the Pygments style. It looks identical to GitHub. -| Installation ~~~~~~~~~~~~~~~~ @@ -126,7 +157,6 @@ To install using ``pip``:: pip install sphinx-github-style -| Configuration ~~~~~~~~~~~~~~~ @@ -139,93 +169,58 @@ Add the extension to your ``conf.py`` "sphinx_github_style", ] -... - Optional Configuration Variables =================================== Add any (or none) of the following configuration variables to your ``conf.py`` -``top_level`` -^^^^^^^^^^^^^^^^^^^ - -.. code-block:: python - - top_level: str - -The name of the package's top-level module. For this repo, it would be ``sphinx_github_style`` - -... - - -``linkcode_blob`` -^^^^^^^^^^^^^^^^^^^ - -.. code-block:: python - - linkcode_blob: str = "head" - -The blob to link to on GitHub - any of ``"head"``, ``"last_tag"``, or ``"{blob}"`` -* ``head`` (default): links to the most recent commit hash; if this commit is tagged, uses the tag instead -* ``last_tag``: links to the most recent commit tag on the currently checked out branch -* ``blob``: links to any blob you want, for example ``"master"`` or ``"v2.0.1"`` +|top_level|_ + The name of the package's top-level module. For this repo, it would be ``sphinx_github_style`` + **Type:** ``str`` -... - -``linkcode_url`` -^^^^^^^^^^^^^^^^^^^ - -.. code-block:: python - - linkcode_url: str = f"https://github.com/{html_context['github_user']}/{html_context['github_repo']}/{html_context['github_version']}" - -The link to your GitHub repository formatted as ``https://github.com/user/repo`` +| -* If not provided, will attempt to create the link from the ``html_context`` dict +|linkcode_blob|_ + The blob to link to on GitHub - any of ``"head"``, ``"last_tag"``, or ``"{blob}"`` -... + **Type:** ``str`` -``linkcode_link_text`` -^^^^^^^^^^^^^^^^^^^^^^ + **Default:** ``"head"`` -.. code-block:: python + * ``"head"`` (default): links to the most recent commit hash; if this commit is tagged, uses the tag instead + * ``"last_tag"``: links to the most recent commit tag on the currently checked out branch + * ``"blob"``: links to any blob you want, for example ``"master"`` or ``"v2.0.1"`` - linkcode_link_text: str = "View on GitHub" +| +|linkcode_url|_ + The link to your GitHub repository formatted as ``https://github.com/user/repo`` -The text to use for the linkcode link + **Type:** ``str`` -... + **Default:** ``f"https://github.com/{html_context['github_user']}/{html_context['github_repo']}/{html_context['github_version']}"`` -``linkcode_resolve`` -^^^^^^^^^^^^^^^^^^^^^^^^ + * If not provided, will attempt to create the link from the |sphinx+html_context|_ dict -.. code-block:: python +| - linkcode_resolve: Callable +|linkcode_link_text|_ + The text to use for the linkcode link -A ``linkcode_resolve()`` function to use for resolving the link target + **Type:** ``str`` -* Uses default function from |.get_linkcode_resolve|_ if not specified (recommended) + **Default:** ``"View on GitHub"`` | -Noteworthy Components -~~~~~~~~~~~~~~~~~~~~~ - -* |.TDKStyle|_ - Pygments Style for syntax highlighting similar to Github Pretty Lights Dark Theme -* |.TDKMethLexer|_ - Pygments Lexor to add syntax highlighting to methods -* |.get_linkcode_resolve|_ - to link to GitHub source code using ``sphinx.ext.linkcode`` -* |.add_linkcode_node_class|_ - adds a new ``linkcode-link`` class, allowing for CSS styling separately from ``viewcode`` links -* |.github_style|_ - CSS styling for linkcode links (icon + text) +|linkcode_resolve|_ + A ``linkcode_resolve()`` function to use when resolving the link target with |.sphinx.ext.linkcode|_ -| + **Type:** ``Callable`` -Documentation -~~~~~~~~~~~~~~~~ + **Default:** Return value from |.~.get_linkcode_resolve|_ -Full documentation can be found on |RTD|_ diff --git a/README_PyPi.rst b/README_PyPi.rst deleted file mode 100644 index cc70a47..0000000 --- a/README_PyPi.rst +++ /dev/null @@ -1,217 +0,0 @@ -.. Title: Sphinx Github Style -.. Description: A Sphinx extension to add GitHub source code links and syntax highlighting -.. Author: TDKorn (Adam Korn) - -.. |.get_linkcode_resolve| replace:: get_linkcode_resolve() -.. _.get_linkcode_resolve: https://github.com/TDKorn/sphinx-github-style/blob/v1.0.5/sphinx_github_style/__init__.py#L148-L214 -.. |.add_linkcode_node_class| replace:: add_linkcode_node_class() -.. _.add_linkcode_node_class: https://github.com/TDKorn/sphinx-github-style/blob/v1.0.5/sphinx_github_style/add_linkcode_class.py#L9-L24 -.. |.TDKStyle| replace:: TDKStyle -.. _.TDKStyle: https://github.com/TDKorn/sphinx-github-style/blob/v1.0.5/sphinx_github_style/github_style.py#L44-L139 -.. |.TDKMethLexer| replace:: TDKMethLexer -.. _.TDKMethLexer: https://github.com/TDKorn/sphinx-github-style/blob/v1.0.5/sphinx_github_style/meth_lexer.py#L27-L42 -.. |.github_style| replace:: github_style.css -.. _.github_style: https://github.com/tdkorn/sphinx-github-style/blob/v1.0.5/sphinx_github_style/_static/github_style.css -.. |RTD| replace:: ReadTheDocs -.. _RTD: https://sphinx-github-style.readthedocs.io/en/latest/ -.. |Note| replace:: ๐Ÿ“ **Note** -.. |docs| replace:: **Explore the docs ยป** -.. _docs: https://sphinx-github-style.readthedocs.io/en/latest/ - - -sphinx-github-style -------------------- - -.. image:: https://i.imgur.com/v348dOW.png - :alt: Sphinx GitHub Style: GitHub Integration and Pygments Style for Sphinx Documentation - :width: 50% - :align: center - -GitHub source code links and syntax highlighting for Sphinx docs - -|docs|_ - -| - -.. image:: https://img.shields.io/pypi/v/sphinx-github-style?color=eb5202 - :target: https://pypi.org/project/sphinx-github-style/ - :alt: PyPI Version - -.. image:: https://img.shields.io/badge/GitHub-sphinx--github--style-4f1abc - :target: https://github.com/tdkorn/sphinx-github-style/ - :alt: GitHub Repository - -.. image:: https://static.pepy.tech/personalized-badge/sphinx-github-style?period=total&units=none&left_color=grey&right_color=blue&left_text=Downloads - :target: https://pepy.tech/project/sphinx-github-style/ - -.. image:: https://readthedocs.org/projects/sphinx-github-style/badge/?version=latest - :target: https://sphinx-github-style.readthedocs.io/en/latest/?badge=latest - :alt: Documentation Status - -| - -About -~~~~~~~~~~~~~ - -``sphinx-github-style`` is a Sphinx extension that makes your docs look like and link to GitHub - -... - - -GitHub Source Code Links -=============================== - -.. |linkcode| replace:: ``sphinx.ext.linkcode`` -.. _linkcode: https://www.sphinx-doc.org/en/master/usage/extensions/linkcode.html - -**Using** |linkcode|_, a ``View on GitHub`` **link is added to the documentation of every class, method and function:** - -| - -.. image:: https://user-images.githubusercontent.com/96394652/220941352-f5530a56-d338-4b90-b83a-4b22b0f632fe.png - :alt: sphinx github style adds a "View on GitHub" link - -**They link to and highlight the corresponding code block in your GitHub repo:** - -| - -.. image:: https://user-images.githubusercontent.com/96394652/220945912-447173db-2ac7-4e00-bec5-3859753bf687.png - - -| - -+--------------------------------------------+ -| |Note| | -+============================================+ -| These links can be used with/instead of | -| the links added by ``sphinx.ext.viewcode`` | -| | -| * They use a newly added ``linkcode-link`` | -| class which can be styled using CSS | -+--------------------------------------------+ - -| - - -Syntax Highlighting -===================== - -``sphinx-github-style`` **also contains a** ``Pygments`` **style to highlight code in your documentation similar to GitHub:** - -| - -.. image:: https://user-images.githubusercontent.com/96394652/220946796-bf7aa236-964d-48e7-83e2-142aac00b0dd.png - - -| - -Installation -~~~~~~~~~~~~~~~~ - -To install using ``pip``:: - - pip install sphinx-github-style - -| - -Configuration -~~~~~~~~~~~~~~~ - -Add the extension to your ``conf.py`` - -.. code-block:: python - - extensions = [ - "sphinx_github_style", - ] - -... - -Optional Configuration Variables -=================================== - -Add any (or none) of the following configuration variables to your ``conf.py`` - - -``top_level`` -^^^^^^^^^^^^^^^^^^^ - -.. code-block:: python - - top_level: str - -The name of the package's top-level module. For this repo, it would be ``sphinx_github_style`` - -... - - -``linkcode_blob`` -^^^^^^^^^^^^^^^^^^^ - -.. code-block:: python - - linkcode_blob: str = "head" - - -The blob to link to on GitHub - any of ``"head"``, ``"last_tag"``, or ``"{blob}"`` - -* ``head`` (default): links to the most recent commit hash; if this commit is tagged, uses the tag instead -* ``last_tag``: links to the most recent commit tag on the currently checked out branch -* ``blob``: links to any blob you want, for example ``"master"`` or ``"v2.0.1"`` - - -... - -``linkcode_url`` -^^^^^^^^^^^^^^^^^^^ - -.. code-block:: python - - linkcode_url: str = f"https://github.com/{html_context['github_user']}/{html_context['github_repo']}/{html_context['github_version']}" - -The link to your GitHub repository formatted as ``https://github.com/user/repo`` - -* If not provided, will attempt to create the link from the ``html_context`` dict - -... - -``linkcode_link_text`` -^^^^^^^^^^^^^^^^^^^^^^ - -.. code-block:: python - - linkcode_link_text: str = "View on GitHub" - - -The text to use for the linkcode link - -... - -``linkcode_resolve`` -^^^^^^^^^^^^^^^^^^^^^^^^ - -.. code-block:: python - - linkcode_resolve: Callable - -A ``linkcode_resolve()`` function to use for resolving the link target - -* Uses default function from |.get_linkcode_resolve|_ if not specified (recommended) - -| - -Noteworthy Components -~~~~~~~~~~~~~~~~~~~~~ - -* |.TDKStyle|_ - Pygments Style for syntax highlighting similar to Github Pretty Lights Dark Theme -* |.TDKMethLexer|_ - Pygments Lexor to add syntax highlighting to methods -* |.get_linkcode_resolve|_ - to link to GitHub source code using ``sphinx.ext.linkcode`` -* |.add_linkcode_node_class|_ - adds a new ``linkcode-link`` class, allowing for CSS styling separately from ``viewcode`` links -* |.github_style|_ - CSS styling for linkcode links (icon + text) - -| - -Documentation -~~~~~~~~~~~~~~~~ - -Full documentation can be found on |RTD|_ \ No newline at end of file diff --git a/docs/requirements.txt b/docs/requirements.txt index 4c90028..7e6939d 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -4,3 +4,4 @@ docutils<0.17 sphinx-github-style sphinx-inlinecode sphinx-sitemap +sphinx-readme diff --git a/docs/source/README.rst b/docs/source/README.rst index cab34a7..b232b02 100644 --- a/docs/source/README.rst +++ b/docs/source/README.rst @@ -11,21 +11,54 @@ .. _.github_style: https://github.com/tdkorn/sphinx-github-style/tree/v1.0.4/sphinx_github_style/_static/github_style.css +.. only:: pypi + + sphinx-github-style - GitHub source code links and syntax highlighting for Sphinx documentation + ------------------------------------------------------------------------------------------------- + + .. image:: _static/logo_pypi.png + :alt: Sphinx GitHub Style: GitHub Integration and Pygments Style for Sphinx Documentation + :width: 50% + :align: center + + .. raw:: html
-.. image:: _static/logo_square.ico - :alt: Sphinx GitHub Style: GitHub Integration and Pygments Style for Sphinx Documentation - :width: 25% +.. only:: readme + .. image:: _static/logo_square_grey_blue.png + :alt: Sphinx GitHub Style: GitHub Integration and Pygments Style for Sphinx Documentation + :width: 25% -.. raw:: html +.. only:: html + + .. image:: _static/logo_square.ico + :alt: Sphinx GitHub Style: GitHub Integration and Pygments Style for Sphinx Documentation + :width: 25% + +.. only:: readme or html + + .. raw:: html + +

Sphinx Github Style

+ + +GitHub source code links and syntax highlighting for Sphinx documentation + + +.. only:: readme or pypi -

Sphinx Github Style

+ .. |docs| replace:: **Explore the docs ยป** + .. _docs: https://sphinx-github-style.readthedocs.io/en/latest/ -GitHub source code links and syntax highlighting for Sphinx docs + |docs|_ + +.. only:: pypi + + | .. image:: https://img.shields.io/pypi/v/sphinx-github-style?color=eb5202 @@ -49,6 +82,9 @@ GitHub source code links and syntax highlighting for Sphinx docs

+.. only:: pypi + + | About ~~~~~~~~~~~~~ @@ -65,43 +101,54 @@ GitHub Source Code Links Using :mod:`sphinx.ext.linkcode`, a ``View on GitHub`` link is added to the documentation of every class, method, function, and property: +.. only:: pypi + + | + .. only:: html .. autofunction:: sphinx_github_style.__init__.get_repo_dir - :no-index: + :noindex: -.. only:: not html +.. only:: readme or pypi - .. image:: https://user-images.githubusercontent.com/96394652/220941352-f5530a56-d338-4b90-b83a-4b22b0f632fe.png - :alt: sphinx github style adds a "View on GitHub" link + .. image:: _static/github_link.png + :alt: sphinx-github-style adds a "View on GitHub" link They link to and highlight the corresponding code block in your GitHub repository: +.. only:: pypi -.. image:: _static/github_linked_code.png + | +.. image:: _static/github_linked_code.png + :alt: The linked corresponding highlighted source code block on GitHub .. note:: - These links can be used with/instead of the links added by :mod:`sphinx.ext.viewcode` - * They use a newly added ``linkcode-link`` class which can be :doc:`styled using CSS ` - + These links can be :doc:`styled with CSS ` and used with/instead + of the links added by :mod:`sphinx.ext.viewcode` Syntax Highlighting ==================== -``sphinx-github-style`` **also contains a** ``Pygments`` **style to highlight code blocks similar to GitHub:** +``sphinx-github-style`` also contains a ``Pygments`` style to highlight code blocks similar to GitHub: + +.. only:: html + + .. literalinclude:: ../../sphinx_github_style/__init__.py + :language: python + :lines: 230-246 +.. only:: readme or pypi -.. literalinclude:: ../../sphinx_github_style/__init__.py - :language: python - :lines: 230-246 + .. image:: _static/syntax_highlighting.png + :alt: A code block highlighted by the Pygments style. It looks identical to GitHub. -| Installation ~~~~~~~~~~~~~~~~ @@ -110,7 +157,6 @@ To install using ``pip``:: pip install sphinx-github-style -| Configuration ~~~~~~~~~~~~~~~ @@ -128,62 +174,57 @@ Optional Configuration Variables Add any (or none) of the following configuration variables to your ``conf.py`` +.. only:: not readme and not pypi -``top_level`` -^^^^^^^^^^^^^^^^^^^ - -.. confval:: top_level - - The name of the package's top-level module. For this repo, it would be ``sphinx_github_style`` + .. include:: configuration.rst.src - :type: **str** +.. only:: readme or pypi -``linkcode_blob`` -^^^^^^^^^^^^^^^^^^^ + :confval:`top_level` + The name of the package's top-level module. For this repo, it would be ``sphinx_github_style`` -.. confval:: linkcode_blob + **Type:** ``str`` - The blob to link to on GitHub - any of ``"head"``, ``"last_tag"``, or ``"{blob}"`` + | - * ``head`` (default): links to the most recent commit hash; if this commit is tagged, uses the tag instead - * ``last_tag``: links to the most recent commit tag on the currently checked out branch - * ``blob``: links to any blob you want, for example ``"master"`` or ``"v2.0.1"`` + :confval:`linkcode_blob` + The blob to link to on GitHub - any of ``"head"``, ``"last_tag"``, or ``"{blob}"`` - :type: **str** - :default: ``"head"`` + **Type:** ``str`` + **Default:** ``"head"`` -``linkcode_url`` -^^^^^^^^^^^^^^^^^^^ + * ``"head"`` (default): links to the most recent commit hash; if this commit is tagged, uses the tag instead + * ``"last_tag"``: links to the most recent commit tag on the currently checked out branch + * ``"blob"``: links to any blob you want, for example ``"master"`` or ``"v2.0.1"`` -.. confval:: linkcode_url + | - The link to your GitHub repository formatted as ``https://github.com/user/repo`` + :confval:`linkcode_url` + The link to your GitHub repository formatted as ``https://github.com/user/repo`` - * If not provided, will attempt to create the link from the :external+sphinx:confval:`html_context` dict + **Type:** ``str`` - :type: **str** - :default: ``f"https://github.com/{html_context['github_user']}/{html_context['github_repo']}/{html_context['github_version']}"`` + **Default:** ``f"https://github.com/{html_context['github_user']}/{html_context['github_repo']}/{html_context['github_version']}"`` + * If not provided, will attempt to create the link from the :external+sphinx:confval:`html_context` dict -``linkcode_link_text`` -^^^^^^^^^^^^^^^^^^^^^^ + | -.. confval:: linkcode_link_text + :confval:`linkcode_link_text` + The text to use for the linkcode link - The text to use for the linkcode link + **Type:** ``str`` - :type: **str** - :default: ``"View on GitHub"`` + **Default:** ``"View on GitHub"`` + | -``linkcode_resolve`` -^^^^^^^^^^^^^^^^^^^^^^^^ + :confval:`linkcode_resolve` + A ``linkcode_resolve()`` function to use when resolving the link target with :mod:`sphinx.ext.linkcode` -.. confval:: linkcode_resolve + **Type:** ``Callable`` - A ``linkcode_resolve()`` function to use when resolving the link target with :mod:`sphinx.ext.linkcode` + **Default:** Return value from :func:`~.get_linkcode_resolve` - :type: **Callable** - :default: Return value from :func:`~.get_linkcode_resolve` diff --git a/docs/source/_static/github_link.png b/docs/source/_static/github_link.png new file mode 100644 index 0000000..25960f3 Binary files /dev/null and b/docs/source/_static/github_link.png differ diff --git a/docs/source/_static/logo_pypi.png b/docs/source/_static/logo_pypi.png new file mode 100644 index 0000000..7065463 Binary files /dev/null and b/docs/source/_static/logo_pypi.png differ diff --git a/docs/source/_static/syntax_highlighting.png b/docs/source/_static/syntax_highlighting.png new file mode 100644 index 0000000..21ccdb9 Binary files /dev/null and b/docs/source/_static/syntax_highlighting.png differ diff --git a/docs/source/conf.py b/docs/source/conf.py index 6388ac5..310caeb 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -123,6 +123,7 @@ 'sphinx_github_style', 'sphinx_inlinecode', 'sphinx_sitemap', + 'sphinx_readme', ] # ====================== Extra Settings for Extensions ======================== @@ -162,6 +163,8 @@ else: # For gh-pages use master linkcode_blob = 'master' + # For sphinx_readme image links in README + readme_blob = 'master' # Text to use for the linkcode link linkcode_link_text = "View on GitHub" @@ -170,6 +173,22 @@ linkcode_url = f"https://github.com/{html_context['github_user']}/{repo}" +# ~~~~ Sphinx README ~~~~ +# +# Blob to use when linking to GitHub source code +readme_src_files = 'README.rst' + +readme_docs_url_type = 'html' + +# Settings to uncomment when generating PyPi README + +# readme_tags = ["pypi"] +# +# readme_raw_directive = False +# +# readme_inline_markup = False + + # ---- Skip and Setup Method ------------------------------------------------- diff --git a/docs/source/configuration.rst.src b/docs/source/configuration.rst.src new file mode 100644 index 0000000..d3478b9 --- /dev/null +++ b/docs/source/configuration.rst.src @@ -0,0 +1,59 @@ + +``top_level`` +^^^^^^^^^^^^^^^^^^^ + +.. confval:: top_level + + The name of the package's top-level module. For this repo, it would be ``sphinx_github_style`` + + :type: ``str`` + + +``linkcode_blob`` +^^^^^^^^^^^^^^^^^^^ + +.. confval:: linkcode_blob + + The blob to link to on GitHub - any of ``"head"``, ``"last_tag"``, or ``"{blob}"`` + + * ``head`` (default): links to the most recent commit hash; if this commit is tagged, uses the tag instead + * ``last_tag``: links to the most recent commit tag on the currently checked out branch + * ``blob``: links to any blob you want, for example ``"master"`` or ``"v2.0.1"`` + + :type: ``str`` + :default: ``"head"`` + + +``linkcode_url`` +^^^^^^^^^^^^^^^^^^^ + +.. confval:: linkcode_url + + The link to your GitHub repository formatted as ``https://github.com/user/repo`` + + * If not provided, will attempt to create the link from the :external+sphinx:confval:`html_context` dict + + :type: ``str`` + :default: ``f"https://github.com/{html_context['github_user']}/{html_context['github_repo']}/{html_context['github_version']}"`` + + +``linkcode_link_text`` +^^^^^^^^^^^^^^^^^^^^^^ + +.. confval:: linkcode_link_text + + The text to use for the linkcode link + + :type: ``str`` + :default: ``"View on GitHub"`` + + +``linkcode_resolve`` +^^^^^^^^^^^^^^^^^^^^^^^^ + +.. confval:: linkcode_resolve + + A ``linkcode_resolve()`` function to use when resolving the link target with :mod:`sphinx.ext.linkcode` + + :type: ``Callable`` + :default: Return value from :func:`~.get_linkcode_resolve` diff --git a/setup.py b/setup.py index 64aa9ce..590ba80 100644 --- a/setup.py +++ b/setup.py @@ -2,7 +2,7 @@ from pathlib import Path from setuptools import setup, find_packages -LONG_DESCRIPTION_SRC = 'README_PyPi.rst' +LONG_DESCRIPTION_SRC = 'README.rst' def read(file):