Added polyversion support.

docs/poly.py

@@ -0,0 +1,87 @@
+from datetime import datetime
+from pathlib import Path
+
+from sphinx_polyversion.api import apply_overrides
+from sphinx_polyversion.driver import DefaultDriver
+from sphinx_polyversion.git import Git, GitRef, GitRefType, file_predicate, refs_by_type
+from sphinx_polyversion.pyvenv import Poetry
+from sphinx_polyversion.sphinx import SphinxBuilder
+
+#: Regex matching the branches to build docs for
+BRANCH_REGEX = r"docs"
+
+#: Regex matching the tags to build docs for
+TAG_REGEX = r"v7.1|v7.0|v6.2|v6.1|v6.0"
+
+#: Output dir relative to project root
+OUTPUT_DIR = "docs/build"
+
+#: Source directory
+SOURCE_DIR = "docs/"
+
+#: Arguments to pass to `poetry install`
+POETRY_ARGS = "--sync"
+
+#: Arguments to pass to `sphinx-build`
+SPHINX_ARGS = "-a -v"
+
+#: Mock data used for building local version
+MOCK_DATA = {
+    "revisions": [
+        GitRef("v1.8.0", "", "", GitRefType.TAG, datetime.fromtimestamp(0)),
+        GitRef("v1.9.3", "", "", GitRefType.TAG, datetime.fromtimestamp(1)),
+        GitRef("v1.10.5", "", "", GitRefType.TAG, datetime.fromtimestamp(2)),
+        GitRef("master", "", "", GitRefType.BRANCH, datetime.fromtimestamp(3)),
+        GitRef("dev", "", "", GitRefType.BRANCH, datetime.fromtimestamp(4)),
+        GitRef("some-feature", "", "", GitRefType.BRANCH, datetime.fromtimestamp(5)),
+    ],
+    "current": GitRef("local", "", "", GitRefType.TAG, datetime.fromtimestamp(6)),
+}
+MOCK = False
+
+
+#: Data passed to templates
+def data(driver, rev, env):
+    revisions = driver.targets
+    branches, tags = refs_by_type(revisions)
+    latest = max(tags or branches)
+    return {
+        "current": rev,
+        "tags": tags,
+        "branches": branches,
+        "revisions": revisions,
+        "latest": latest,
+    }
+
+
+def root_data(driver):
+    revisions = driver.builds
+    branches, tags = refs_by_type(revisions)
+    latest = max(tags or branches)
+    return {"revisions": revisions, "latest": latest}
+
+
+# Load overrides read from commandline to global scope
+apply_overrides(globals())
+# Determine repository root directory
+root = Git.root(Path(__file__).parent)
+
+# Setup driver and run it
+src = Path(SOURCE_DIR)
+DefaultDriver(
+    root,
+    OUTPUT_DIR,
+    vcs=Git(
+        branch_regex=BRANCH_REGEX,
+        tag_regex=TAG_REGEX,
+        buffer_size=1 * 10**9,  # 1 GB
+        predicate=file_predicate([src]),  # exclude refs without source dir
+    ),
+    builder=SphinxBuilder(src / "source", args=SPHINX_ARGS.split()),
+    env=Poetry.factory(args=POETRY_ARGS.split()),
+    template_dir=root / src / "templates",
+    static_dir=root / src / "static",
+    data_factory=data,
+    root_data_factory=root_data,
+    mock=MOCK_DATA,
+).run(MOCK)

docs/source/_templates/components/edit-this-page.html

@@ -0,0 +1,41 @@
+{# Adjust link of `edit source` button The furo theme adds an `edit source`
+button to the top of the page that opens the page viewed on github in edit mode.
+However we prefer opening the file in the standards view mode. The furo theme is
+based on the `basic-ng` theme which defines a view-this-page button. We reuse
+its code to determine the page link but extend it to use the meta field
+`edit_path` that can be set in every .rst file to change the path the edit
+button links to. See
+https://www.sphinx-doc.org/en/master/usage/restructuredtext/field-lists.html#file-wide-metadata
+#} {% extends "furo/components/edit-this-page.html" %} {% from
+"furo/components/edit-this-page.html" import furo_edit_button with context %} {%
+from "basic-ng/components/edit-this-page.html" import sanitise_trailing_slash
+with context %} {#- Modified from
+https://github.com/pradyunsg/sphinx-basic-ng/blob/main/src/sphinx_basic_ng/theme/basic-ng/components/view-this-page.html#L5
+#} {%- macro determine_page_view_link() -%} {%- if theme_source_view_link -%} {{
+theme_source_view_link.format(filename=pagename+page_source_suffix) }} {%- elif
+theme_source_repository -%} {#- First, sanitise the trailing slashes. -#} {%-
+set repo = sanitise_trailing_slash(theme_source_repository) -%} {%- set branch =
+theme_source_branch -%} {%- set subdirectory =
+sanitise_trailing_slash(theme_source_directory) -%} {#- Figure out the
+document's source file path. -#} {% if meta.edit_path %} {# Modify path based on
+the meta field `edit_path` #} {% if meta.edit_path.startswith("/") %} {%- set
+relative_path = meta.edit_path[1:] -%} {%- set subdirectory = "" -%} {%- else
+-%} {%- set relative_path = meta.edit_path -%} {%- endif -%} {%- else -%} {%-
+set relative_path = pagename + page_source_suffix -%} {%- endif -%} {%- if not
+subdirectory -%} {%- set document_path = relative_path -%} {%- else -%} {%- set
+document_path = subdirectory + "/" + relative_path -%} {%- endif -%} {#- Don't
+allow http:// URLs -#} {%- if repo.startswith( ( "http://github.com/",
+"http://gitlab.com/", "http://bitbucket.org/", ) ) -%} {{ warning("Could not use
+`source_repository` provided. Please use https:// links in your `conf.py` file's
+`html_theme_options`.") }} {#- Handle the relevant cases -#} {%- elif
+repo.startswith("https://github.com/") -%} {{ repo }}/blob/{{ branch }}/{{
+document_path }} {%- elif repo.startswith("https://gitlab.com/") -%} {{ repo
+}}/blob/{{ branch }}/{{ document_path }} {%- elif
+repo.startswith("https://bitbucket.org/") -%} {{ repo }}/src/{{ branch }}/{{
+document_path }} {#- Fail with a warning -#} {%- else -%} {{ warning( "Could not
+understand `source_repository` provided: " + repo + "\n" + "You should set
+`source_view_link`, so that the view link is presented." ) }} {%- endif -%} {%-
+elif show_source and has_source -%} {{ pathto('_sources/' + sourcename, true) }}
+{%- endif -%} {%- endmacro -%} {# use the edit button code by furo but use above
+macro to determine URL #} {% block link_available -%} {{
+furo_edit_button(determine_page_view_link()) }} {%- endblock %}

docs/source/_templates/sidebar/brand.html

@@ -0,0 +1,6 @@
+{# Style darglint logo in the sidebar This adds the version number as a
+superscript. #} {% extends "!sidebar/brand.html" %} {% block brand_content %}
+<span class="sidebar-brand-text"
+    >{{ project }}<sup><i>{{ release }}</i></sup></span
+>
+{% endblock brand_content %}

docs/source/_templates/versioning.html

@@ -0,0 +1,48 @@
+{# Add version selector This generates a version selector similar to the rtd
+version selector using the data exposed by `sphinx-multiversion` through
+current, latest_version and versions. It uses the same classes and ids as the
+version picker provided by the theme for use with readthedocs.io The css styling
+can be found in `css/version-selector.css`. The template doesn't fail when the
+needed data isn't provided but the result doesn't work as expected. #}
+
+<div
+    id="furo-readthedocs-versions"
+    class="rst-versions"
+    data-toggle="rst-versions"
+    role="note"
+    aria-label="{{ _('Versions') }}"
+    tabindex="0"
+>
+    {# this element shows the current version and is visible by default It hides
+    on hover while the element below becomes appears in its place. #}
+    <span class="rst-current-version" data-toggle="rst-current-version">
+        {# git icon indicating the version selector #}
+        <i class="bi bi-git"></i>
+        {# show current version; prepend `v` in case of branches #} {% if not
+        current or not current.name.startswith("v") %} v: {% endif %} {{
+        current.name if current else "undefined" }}
+    </span>
+    {% if revisions %} {# This item lists the avaible versions grouped into
+    branches and tags. The item is hidden by default but appears when the user
+    hovers over the version selector. #}
+    <div class="rst-other-versions">
+        {% if tags %} {# List of tags #}
+        <dl>
+            <dt>
+                <i class="bi bi-tags-fill version-header"></i>{{ _('Tags') }}
+            </dt>
+            {% for item in tags %}
+            <dd><a href="../{{ item.name }}/index.html">{{ item.name }}</a></dd>
+            {% endfor %}
+        </dl>
+        {% endif %} {% if branches %} {# List of branches #}
+        <dl>
+            <dt><i class="bi bi-git version-header"></i>{{ _('Branches') }}</dt>
+            {% for item in branches %}
+            <dd><a href="../{{ item.name }}/index.html">{{ item.name }}</a></dd>
+            {% endfor %}
+        </dl>
+        {% endif %}
+    </div>
+    {% endif %}
+</div>

docs/source/conf.py

@@ -13,6 +13,14 @@
 
 import os
 
+from sphinx_polyversion import load
+from sphinx_polyversion.git import GitRef
+
+# -- Load versioning data ----------------------------------------------------
+
+data = load(globals())  # adds variables `current` and `revisions`
+current: GitRef = data["current"]
+
 # 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.
@@ -143,8 +151,12 @@
     "https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.0.0/css/fontawesome.min.css",
     "https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.0.0/css/solid.min.css",
     "https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.0.0/css/brands.min.css",
+    #
+    # style the version selector
+    "css/version-selector.css",
 ]
 
+
 # html_theme_path = []
 
 # The name for this set of Sphinx documents.  If None, it defaults to
@@ -182,7 +194,16 @@
 # html_use_smartypants = True
 
 # Custom sidebar templates, maps document names to template names.
-# html_sidebars = {}
+html_sidebars = {
+    "**": [
+        "sidebar/brand.html",  # override `furo/sidebar/brand.html`
+        "sidebar/search.html",
+        "sidebar/scroll-start.html",
+        "sidebar/navigation.html",
+        "sidebar/scroll-end.html",
+        "versioning.html",
+    ],
+}
 
 # Additional templates that should be rendered to pages, maps page names to
 # template names.

docs/templates/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+
+<html>
+    <head>
+        <title>Redirecting to master branch</title>
+        <meta charset="utf-8" />
+        <meta
+            http-equiv="refresh"
+            content="0; url=./{{ latest.name }}/index.html"
+        />
+        <link rel="canonical" href="./{{ latest.name }}/index.html" />
+    </head>
+</html>

pyproject.toml

@@ -49,6 +49,7 @@ flake8 = "5.0.4"
 flake8-import-order = "^0.18.2"
 flake8-docstrings = "^1.7.0"
 flake8-rst-docstrings = "^0.3.0"
+sphinx-polyversion = "^1.0.0"
 
 [tool.poetry_bumpversion.file."pysnmp/__init__.py"]