Update docs

.github/workflows/docs.yml

@@ -14,6 +14,7 @@ jobs:
     - uses: ammaraskar/sphinx-action@master
       with:
         docs-folder: "docs/"
+        pre-build-command: "pip install -r requirements.txt"
 
      # Create an artifact of the html output.
     - uses: actions/upload-artifact@v1

.readthedocs.yaml

@@ -0,0 +1,27 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Build PDF & ePub
+formats: all
+
+# Set the version of Python and other tools you might need
+build:
+  os: ubuntu-20.04
+  tools:
+    python: "3.10"
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+   configuration: docs/source/conf.py
+
+# Optionally declare the Python requirements required to build your docs
+python:
+   install:
+   - method: pip
+     path: .
+   - requirements: docs/requirements.txt
+   - requirements: requirements.txt

docs/source/README.rst

@@ -118,70 +118,56 @@ Optional Configuration Variables
 
 Add any of the following configuration variables to your ``conf.py``
 
-``top_level``
-^^^^^^^^^^^^^^^^^^^
-
-.. code-block:: python
-
-   top_level: str
-
-
-The name of the top-level package. For this repo, it would be ``sphinx_github_style``
-
-...
 
 ``linkcode_blob``
 ^^^^^^^^^^^^^^^^^^^
 
-.. code-block:: python
-
-   linkcode_blob: str = "head"
-
+.. confval:: linkcode_blob
 
-The blob to link to on GitHub - any of ``"head"``, ``"last_tag"``, or ``"{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 recently tagged commit; if no tags exist, uses ``head``
-* ``blob``: links to any blob you want, for example ``"master"`` or ``"v2.0.1"``
+   * ``head`` (default): links to the most recent commit hash; if this commit is tagged, uses the tag instead
+   * ``last_tag``: links to the most recently tagged commit; if no tags exist, uses ``head``
+   * ``blob``: links to any blob you want, for example ``"master"`` or ``"v2.0.1"``
 
+   :type: **str**
+   :default: ``"head"``
 
-...
 
 ``linkcode_url``
 ^^^^^^^^^^^^^^^^^^^
 
-.. code-block:: python
+.. confval:: linkcode_url
 
-   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``
 
-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
 
-* If not provided, will attempt to create the link from the ``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``
 ^^^^^^^^^^^^^^^^^^^^^^
 
-.. code-block:: python
-
-   linkcode_link_text: str = "View on GitHub"
+.. confval:: linkcode_link_text
 
+   The text to use for the linkcode link
 
-The text to use for the linkcode link
+   :type: **str**
+   :default: ``"View on GitHub"``
 
-...
 
 ``linkcode_resolve``
 ^^^^^^^^^^^^^^^^^^^^^^^^
 
-.. code-block:: python
+.. confval:: linkcode_resolve
 
-   linkcode_resolve: types.FunctionType
+   A ``linkcode_resolve()`` function to use when resolving the link target with :mod:`sphinx.ext.linkcode`
 
-A ``linkcode_resolve()`` function to use for resolving the link target
+   :type: **Callable**
+   :default: Return value from :func:`~.get_linkcode_resolve`
 
-* Uses default function from :func:`~.get_linkcode_resolve` if not specified (recommended)
 
 |
 

docs/source/_static/custom.css

@@ -20,4 +20,9 @@ code.literal {
 .rst-content .viewcode-back, .rst-content .viewcode-link {
     color: #00e;
     padding-left: 12px;
+}
+/*Hide headers for config values; allows confval directives to be accessible via TOC*/
+#optional-configuration-variables h3 {
+    visibility: hidden;
+    display: none !important;
 }

docs/source/conf.py

@@ -102,6 +102,9 @@
     'github_repo': repo,
 }
 
+if 'html' not in sys.argv:
+    pygments_style = 'sphinx'
+
 if not on_rtd:
     site_url = "https://tdkorn.github.io/sphinx-github-style/"
 
@@ -184,5 +187,30 @@ def skip(app, what, name, obj, would_skip, options):
 
 
 def setup(app):
+    from sphinx.domains.python import PyField
+    from sphinx.util.docfields import Field
+    from sphinx.locale import _
+
     app.connect('autodoc-skip-member', skip)
     app.add_css_file("custom.css")
+    app.add_object_type(
+        'confval',
+        'confval',
+        objname='configuration value',
+        indextemplate='pair: %s; configuration value',
+        doc_field_types=[
+            PyField(
+                'type',
+                label=_('Type'),
+                has_arg=False,
+                names=('type',),
+                bodyrolename='class'
+            ),
+            Field(
+                'default',
+                label=_('Default'),
+                has_arg=False,
+                names=('default',),
+            ),
+        ]
+    )

sphinx_github_style/add_linkcode_class.py

@@ -7,9 +7,9 @@
 
 
 def add_linkcode_node_class(app: Sphinx, doctree: Node, docname: str) -> None:
-    """Changes every :class:`~.Node` added by linkcode to use the ``"linkcode-link"`` class
+    """Changes every :class:`~.Node` added by :mod:`sphinx.ext.linkcode` to use the ``"linkcode-link"`` class
 
-    This creates separation from the nodes added by ``sphinx.ext.viewcode``, allowing
+    This creates separation from the nodes added by :mod:`sphinx.ext.viewcode`, allowing
     for different link text and CSS styling
 
     Sets the link text to ``linkcode_link_text``, or ``"View on GitHub"`` if not provided