Added versioning selector.

docs/source/_static/css/version-selector.css

@@ -0,0 +1,65 @@
+/* Style our version picker
+
+The version picker is defined in `_templates/versioning.html` and uses the same classes
+and ids as the one provided by the theme for use with readthedocs.io
+This allows us to load the styles by readthedocs as a basis
+and adjust them to our likings.
+*/
+
+/* Import RTD styles */
+@import url("https://assets.readthedocs.org/static/css/readthedocs-doc-embed.css");
+@import url("https://assets.readthedocs.org/static/css/badge_only.css");
+
+/* remove border around version picker */
+#furo-readthedocs-versions:focus-within,
+#furo-readthedocs-versions:hover {
+    box-shadow: none;
+}
+
+/* adjust the element showing the selected version */
+.rst-versions .rst-current-version {
+    padding: var(--sidebar-item-spacing-vertical)
+        var(--sidebar-item-spacing-horizontal);
+    border-top: 1px solid var(--color-sidebar-search-border);
+    color: var(--color-foreground-primary);
+}
+
+/* .rst-versions .rst-current-version.rst-out-of-date {
+    color: #c64334;
+}
+
+.rst-versions .rst-current-version.rst-active-old-version {
+    color: #634f00;
+} */
+
+/* adjust the element listing all available versions */
+#furo-readthedocs-versions > .rst-other-versions {
+    padding: var(--sidebar-item-spacing-vertical)
+        var(--sidebar-item-spacing-horizontal);
+    border-style: none;
+    border-top: 1px solid var(--color-sidebar-search-border);
+}
+
+/* adjust list headings */
+.rst-versions .rst-other-versions dt {
+    color: var(--color-foreground-secondary);
+}
+
+/* adjust selectable version items */
+.rst-versions .rst-other-versions dd a {
+    color: var(--color-sidebar-link-text--top-level);
+    padding-left: 0px;
+    padding-right: 12px;
+}
+
+/* adjust icons for the list headings */
+.bi.version-header {
+    margin-right: 1ch;
+}
+
+/* adjust icon for the version picker */
+.rst-current-version .bi-git {
+    float: left;
+    color: var(--color-foreground-primary);
+    left: var(--sidebar-item-spacing-horizontal);
+}

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.
@@ -56,7 +64,7 @@
 master_doc = "index"
 
 # General information about the project.
-project = "SNMP Library for Python 6.1"
+project = "SNMP Library for Python"
 copyright = "2005-2020, Ilya Etingof. © Copyright 2022-2024, LeXtudio Inc."
 author = "LeXtudio Inc. <[email protected]>"
 
@@ -143,8 +151,15 @@
     "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",
+    #
+    # load the open source bootstrap icon set
+    "https://cdn.jsdelivr.net/npm/[email protected]/font/bootstrap-icons.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 +197,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.