Fixed docs and tests

CHANGELOG.rst

@@ -10,45 +10,14 @@ and this project adheres to `Semantic Versioning <https://semver.org/spec/v2.0.0
 Unreleased_
 -----------
 
-Added:
+Nothing yet
 
-- When you make a change, put it here
 
-
-0.2_ - YYYY-MM-DD
------------------
-
-Added:
-
-- A new feature
-
-Changed:
-
-- A change in existing functionality
-
-Deprecated:
-
-- A soon-to-be removed feature
-
-Removed:
-
-- A feature that has now been removed
-
-Fixed:
-
-- A bug fix
-
-Security:
-
-- A vulnerability that has been patched
-
-
-0.1_ - YYYY-MM-DD
+0.1_ - 2021-09-21
 -----------------
 
 Initial release
 
 
-.. _Unreleased: https://github.com/dls-controls/sphinx_rtd_theme_github_versions/compare/0.2...HEAD
-.. _0.2: https://github.com/dls-controls/sphinx_rtd_theme_github_versions/compare/0.1...0.2
+.. _Unreleased: https://github.com/dls-controls/sphinx_rtd_theme_github_versions/compare/0.1...HEAD
 .. _0.1: https://github.com/dls-controls/sphinx_rtd_theme_github_versions/releases/tag/0.1

Pipfile

@@ -19,6 +19,7 @@ pytest-mypy = "*"
 pytest-flake8 = "*"
 pytest-black = "*"
 flake8-isort = "*"
+types-docutils = "*"
 isort = ">5.0"
 
 [packages]

README.rst

@@ -13,7 +13,7 @@ Documentation  https://dls-controls.github.io/sphinx_rtd_theme_github_versions
 Changelog      https://github.com/dls-controls/sphinx_rtd_theme_github_versions/blob/master/CHANGELOG.rst
 ============== ==============================================================
 
-TODO: add screenshot
+|screenshot|
 
 .. |code_ci| image:: https://github.com/dls-controls/sphinx_rtd_theme_github_versions/workflows/Code%20CI/badge.svg?branch=master
     :target: https://github.com/dls-controls/sphinx_rtd_theme_github_versions/actions?query=workflow%3A%22Code+CI%22
@@ -41,4 +41,6 @@ TODO: add screenshot
     Anything below this line is used when viewing README.rst and will be replaced
     when included in index.rst
 
+.. |screenshot| image:: https://raw.githubusercontent.com/dls-controls/sphinx_rtd_theme_github_versions/master/docs/images/screenshot.png
+
 See https://dls-controls.github.io/sphinx_rtd_theme_github_versions for more detailed documentation.

docs/conf.py

@@ -4,18 +4,7 @@
 # list see the documentation:
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
 
-# -- Path setup --------------------------------------------------------------
-
-# If extensions (or modules to document with autodoc) are in another directory,
-# add these directories to sys.path here. If the directory is relative to the
-# documentation root, use os.path.abspath to make it absolute, like shown here.
-import os
-import sys
-
-
-sys.path.insert(0, os.path.abspath(os.path.join(__file__, "..", "..")))
-
-import sphinx_rtd_theme_github_versions  # noqa
+import sphinx_rtd_theme_github_versions
 
 # -- General configuration ------------------------------------------------
 
@@ -55,7 +44,7 @@
 # generating warnings in "nitpicky mode". Note that type should include the
 # domain name if present. Example entries would be ('py:func', 'int') or
 # ('envvar', 'LD_LIBRARY_PATH').
-nitpick_ignore = [("py:func", "int")]
+nitpick_ignore = [("class", "str")]
 
 # Both the class’ and the __init__ method’s docstring are concatenated and
 # inserted into the main body of the autoclass directive
@@ -74,9 +63,6 @@
 # role, that is, for text marked up `like this`
 default_role = "any"
 
-# Add any paths that contain templates here, relative to this directory.
-templates_path = ["_templates"]
-
 # The suffix of source filenames.
 source_suffix = ".rst"
 
@@ -93,7 +79,11 @@
 
 # This means you can link things like `str` and `asyncio` to the relevant
 # docs in the python documentation.
-intersphinx_mapping = dict(python=("https://docs.python.org/3/", None))
+intersphinx_mapping = dict(
+    python=("https://docs.python.org/3/", None),
+    sphinx=("https://www.sphinx-doc.org/en/master/", None),
+    sphinx_rtd_theme=("https://sphinx-rtd-theme.readthedocs.io/en/stable/", None),
+)
 
 # A dictionary of graphviz graph attributes for inheritance diagrams.
 inheritance_graph_attrs = dict(rankdir="TB")
@@ -109,7 +99,7 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = "sphinx_rtd_theme"
+html_theme = "sphinx_rtd_theme_github_versions"
 
 # Options for the sphinx rtd theme, use DLS blue
 html_theme_options = dict(style_nav_header_background="rgb(7, 43, 93)")
@@ -131,3 +121,32 @@
 # Logo
 html_logo = "images/dls-logo.svg"
 html_favicon = "images/dls-favicon.ico"
+
+
+# Extensions to theme docs
+# https://github.com/readthedocs/sphinx_rtd_theme/blob/1.0.0/docs/conf.py#L85-L110
+def setup(app):
+    from sphinx.domains.python import PyField
+    from sphinx.util.docfields import Field
+
+    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",),
+            ),
+        ],
+    )

docs/explanations/how-it-works.rst

@@ -1,4 +1,13 @@
 How it works
 ============
 
-Explain how the version fetching works
+The theme works by injecting some javascript that populates the version list
+at runtime. This javascript does the following:
+
+- Fetch the set of all directories in the ``gh-pages`` branch of the ``project`` repo in `github_org`
+- Take the `versions_branches`, and add the names of all the tags in that repo
+- Make a link to github.io for each version that has a directory in ``gh-pages``
+
+You should make sure that there are appropriately named branches in the
+``gh-pages`` branch by doing something like
+https://github.com/dls-controls/sphinx_rtd_theme_github_versions/blob/master/.github/workflows/docs.yml

docs/how-to/configure-the-theme.rst

@@ -1,7 +1,36 @@
 Configure the theme
 ===================
 
-Explain the options
+The following options can be defined in your project's ``conf.py`` file, using
+the :confval:`html_theme_options <sphinx:html_theme_options>` configuration option.
 
-- versions_branches
-- github_org
+For example:
+
+.. code-block:: python
+
+    html_theme_options = {
+        'versions_branches': 'main master',
+        'github_org': 'dls-controls',
+    }
+
+
+Theme Options
+-------------
+
+.. confval:: versions_branches
+
+    The branches that should appear top of the list of versions before all the
+    tags. Should be supplied as a space separated string.
+
+    :type: str
+    :default: ``"main master"``
+
+.. confval:: github_org
+
+    The github organization that the repo is hosted under
+
+    :type: str
+    :default: ``"dls-controls"``
+
+All other `sphinx_rtd_theme options <sphinx_rtd_theme:configuring>` like
+:std:confval:`style_nav_header_background` are also supported.

docs/index.rst

@@ -1,6 +1,8 @@
 .. include:: ../README.rst
     :end-before: when included in index.rst
 
+.. |screenshot| image:: images/screenshot.png
+
 How the documentation is structured
 -----------------------------------
 
@@ -57,7 +59,7 @@ Technical reference material, for classes, methods, APIs, commands, and contribu
     :hidden:
 
     reference/contributing
-    Changelog <https://github.com/dls-controls/{{ cookiecutter.project_name }}/blob/master/CHANGELOG.rst>
+    Changelog <https://github.com/dls-controls/sphinx_rtd_theme_github_versions/blob/master/CHANGELOG.rst>
 
 .. rst-class:: endcolumns
 

docs/tutorials/installation.rst

@@ -42,7 +42,14 @@ from github::
 
     python3 -m pip install git+git://github.com/dls-controls/sphinx_rtd_theme_github_versions.git
 
-The library should now be installed and the commandline interface on your path.
-You can check the version that has been installed by typing::
 
-    sphinx_rtd_theme_github_versions --version
+Including in Sphinx Documentation
+---------------------------------
+
+Set the theme by declaring the `html_theme` in your ``conf.py`` file:
+
+.. code-block:: python
+
+    html_theme = "sphinx_rtd_theme_github_versions"
+
+See `../how-to/configure-the-theme` for more details on configuring the theme

sphinx_rtd_theme_github_versions/__init__.py

@@ -5,7 +5,8 @@
 from ._version_git import __version__
 
 
-# See https://www.sphinx-doc.org/en/master/development/theming.html#distribute-your-theme-as-a-python-package
+# See https://www.sphinx-doc.org/en/master/development/theming.html
+#         #distribute-your-theme-as-a-python-package
 def setup(app):
     # Register the theme that can be referenced without adding a theme path
     app.add_html_theme(

sphinx_rtd_theme_github_versions/theme.conf

@@ -3,21 +3,5 @@ inherit = sphinx_rtd_theme
 pygments_style = sphinx
 
 [options]
-# These are inherited from sphinx_rtd_theme
-canonical_url =
-analytics_id =
-analytics_anonymize_ip = False
-collapse_navigation = True
-sticky_navigation = True
-navigation_depth = 4
-includehidden = True
-titles_only =
-logo_only =
-display_version = True
-prev_next_buttons_location = bottom
-style_external_links = False
-style_nav_header_background =
-vcs_pageview_mode =
-# These are added by our theme
 versions_branches = main master
 github_org = dls-controls