In RTD, versions are no longer available in HTML context (#45)

* Add READTHEDOCS to context * RTD: versions no longer available in context * Include header-links in the quick-start guide * Update version numbers
danirus · Nov 28, 2024 · 6bd8ca7 · 6bd8ca7
1 parent 0ea8ea8
commit 6bd8ca7
Show file tree

Hide file tree

Showing 12 changed files with 153 additions and 103 deletions.
diff --git a/ChangeLog.md b/ChangeLog.md
@@ -1,5 +1,11 @@
 # Change Log
 
+## [0.5.3] - 2024-11-28
+
+- ReadTheDocs no longer provides versions in the context of the template.
+- Update quick-start and version-dropdown documents.
+- Update `versions.js` to display the `current_version` given in `conf.py`.
+
 ## [0.5.2] - 2024-11-26
 
 - Increase contrast for body-bg, pre-border-color, and border-color for the light color scheme, in all colorsets.

diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -5,13 +5,13 @@
 import sphinx_nefertiti
 
 
-on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
-if on_rtd:
-    html_theme_path = [sphinx_nefertiti.get_html_theme_path()]
-else:
-    # Add `sphinx_nefertiti` to the python path.
-    PRJ_PATH = Path(__file__).parents[2]
-    sys.path.insert(0, str(PRJ_PATH))
+# on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
+# if on_rtd:
+#     html_theme_path = [sphinx_nefertiti.get_html_theme_path()]
+# else:
+#     # Add `sphinx_nefertiti` to the python path.
+#     PRJ_PATH = Path(__file__).parents[2]
+#     sys.path.insert(0, str(PRJ_PATH))
 
 
 # -- Project information -----------------------------------------------------
@@ -29,10 +29,15 @@
 # The X.Y.Z number.
 release = ".".join(_ver_list[:3])
 
-release_pattern_url = "https://sphinx-nefertiti.readthedocs.io/{release}/"
+docs_fmt_url = "https://sphinx-nefertiti.readthedocs.io/{release}/"
 
 releases = [
+    "latest",
     release,
+    "0.4.2",
+    "0.3.7",
+    "0.2.3",
+    "0.1.13",
 ]
 
 # -- General configuration ---------------------------------------------------
@@ -45,7 +50,7 @@
     'sphinx_design',
     'sphinx_copybutton',
     'sphinx_colorschemed_images',
-    'sphinx_nefertiti'
+    'sphinx_nefertiti',
 ]
 
 myst_enable_extensions = [
@@ -92,10 +97,9 @@
     "repository_url": "https://github.com/danirus/sphinx-nefertiti",
     "repository_name": "sphinx-nefertiti",
 
-    "current_version": f"v{release}",
+    "current_version": "latest",
     "versions": [
-        ("v%s" % item, release_pattern_url.format(release=item))
-        for item in releases
+        (item, docs_fmt_url.format(release=item)) for item in releases
     ],
 
     # "header_links_in_2nd_row": False,

diff --git a/docs/source/quick-start.rst b/docs/source/quick-start.rst
@@ -44,11 +44,12 @@ Customize the theme
 The following features of Nefertiti for Sphinx can be customized:
 
 1. Fonts.
-2. Color set: blue, indigo, purple, pink, red, ...
-3. Pygments styles for light and dark color schemes.
-4. Repository name and URL to display it in the header.
-5. Project version dropdown selector.
-6. Footer links.
+2. Header links
+3. Color set: blue, indigo, purple, pink, red, ...
+4. Pygments styles for light and dark color schemes.
+5. Repository name and URL to display it in the header.
+6. Project version dropdown selector.
+7. Footer links.
 
 
 1. Fonts
@@ -83,8 +84,71 @@ Edit your ``conf.py`` file and add or modify your ``html_theme_options`` setting
         "doc_headers_font": "Georgia",
     }
 
-2. Color sets
-=============
+2. Header links
+===============
+
+Add links to the header of your Sphinx project using header links. They can be mere links or dropdown lists. The user will see an underline below the link whenever it corresponds to the page loaded in the browser.
+
+Header links can be displayed in a second row in the header.
+
+The following content will produced the header of the image below:
+
+.. code-block:: python
+
+    html_theme_options = {
+        # ... other options ...
+        "header_links_in_2nd_row": True,
+        "header_links": [
+            {
+                'text': 'Features',
+                'link': '/features.html',
+            },
+            {
+                "text": "Learn",
+                "dropdown": (
+                    {
+                        "text": "Learn",
+                        "link": "/learn/index.html",
+                    }, {
+                        "text": "Python Types Intro",
+                        "link": "/python-types.html",
+                    }, {
+                        "text": "Concurrency and async/await",
+                        "link": "/async.html",
+                    }, {
+                        "divider": True,
+                    }, {
+                        "text": "Tutorial - User Guide",
+                        "link": "/tutorial/index.html",
+                        "match": "^/tutorial/*",
+                    }, {
+                        "text": "Advanced User Guide",
+                        "link": "/advanced/index.html",
+                        "match": "^/advanced/*"
+                    }
+                )
+            },
+            {
+                'text': 'Release Notes',
+                'link': '/release-notes.html',
+            },
+            {
+                'text': 'Blog',
+                'link': 'https://example.com/blog',
+            },
+        ]
+    }
+
+.. cs_figure:: users-guide/customization/img/rhythm-header-in-2-rows.*
+    :alt: Header links can be displayed in the second row of the header.
+    :width: 90%
+    :align: center
+    :class: border-radius-2
+
+    Read more about customizing the header links in :ref:`header-links`.
+
+3. Colorsets
+============
 
 Another customizable feature of the theme is the color set. In the header of this documentation you can see a dropdown with a palette icon. The colors listed in the dropdown represent the available color sets. Try them to apply the selected color set to this documentation.
 
@@ -99,7 +163,7 @@ To customize the color set in your project add an entry ``style`` to the ``html_
 
 When ``style`` is not given the theme defaults to ``cyan``.
 
-3. Pygments styles
+4. Pygments styles
 ==================
 
 Pygments_ is the package that renders code blocks. Sphinx supports two settings related with pygments:
@@ -115,13 +179,13 @@ If your Sphinx project has code-blocks, try changing the pygments style settings
 
     html_theme_options = {
         # ... other options ...
-        'pygments_style': 'solarized-light',
+        'pygments_light_style': 'solarized-light',
         'pygments_dark_style': 'solarized-dark'
     }
 
 See more code blocks rendered with Pygments in the :ref:`code-blocks` document in Nefertiti User's Guide.
 
-4. Repository data
+5. Repository data
 ==================
 
 If your Sphinx project is about a source code product, and it resides in a Git repository, in GitHub or GitLab, Nefertiti can display information relative to your repository in the header.
@@ -136,7 +200,7 @@ Just add the ``repository_name`` and ``repository_url`` keys to your ``html_them
         "repository_url": "https://github.com/danirus/sphinx-nefertiti",
     }
 
-5. Version dropdown
+6. Version dropdown
 ===================
 
 If your project is available in different versions Nefertiti for Sphinx can display a dropdown in the header to switch between them.
@@ -149,11 +213,11 @@ If you host different versions in different URLs, like:
     * - Version
       - URL
     * - v2.9.9
-      - https://sample-project.readthedocs.io/en/latest/
+      - https://sample-project.org/latest/
     * - v2.8.5
-      - https://sample-project.readthedocs.io/en/2.8.5/
+      - https://sample-project.org/2.8.5/
     * - v2.7.2
-      - https://sample-project.readthedocs.io/en/2.7.2/
+      - https://sample-project.org/2.7.2/
 
 
 Enable the version dropdown by adding the ``versions`` key to your ``html_theme_options`` setting:
@@ -163,32 +227,39 @@ Enable the version dropdown by adding the ``versions`` key to your ``html_theme_
     html_theme_options = {
         # ... other options ...
         "versions": [
-            ("v2.9.9", "https://sample-project.readthedocs.io/en/latest/"),
-            ("v2.8.5", "https://sample-project.readthedocs.io/en/2.8.5/"),
-            ("v2.7.2", "https://sample-project.readthedocs.io/en/2.7.2/"),
+            ("v2.9.9", "https://sample-project.org/latest/"),
+            ("v2.8.5", "https://sample-project.org/2.8.5/"),
+            ("v2.7.2", "https://sample-project.org/2.7.2/"),
         ]
     }
 
-The ``versions`` key in your ``html_theme_options`` is ignored if you use readthedocs_ to host your project (the template ``version-dropdown.html`` renders differently depending on whether the project is hosted in readthedocs_ or not).
 
-
-6. Footer links
+7. Footer links
 ===============
 
-In addition to the copyright notice, configurable with the ``copyright`` Sphinx setting, you can add links that are important to your project, like a link to your company website or a link to your code repository. Footer links are added via the ``footer_links`` key in the ``html_theme_options``. This entry has to be a comma separated list of strings with the format: ``"<link title>|<URL>"``.
+In addition to the copyright notice, configurable with the ``copyright`` Sphinx setting, you can add links that are important to your project, like a link to your company website or a link to your code repository. Footer links are added via the ``footer_links`` key in the ``html_theme_options``. This entry has to be a list of dictionaries.
 
 As an example, the 4 links of the current Nefertiti for Sphinx documentation look like this in the ``html_theme_options`` setting:
 
 .. code-block:: python
 
     html_theme_options = {
         # ... other options ...
-        "footer_links": ",".join([
-            "Documentation|https://sphinx-nefertiti.readthedocs.com",
-            "Package|https://pypi.com/sphinx-nefertiti",
-            "Repository|https://github.com/danirus/sphinx-nefertiti",
-            "Issues|https://github.com/danirus/sphinx-nefertiti/issues",
-        ])
+        "footer_links": [
+            {
+                "text": "Documentation",
+                "link": "https://sphinx-nefertiti.readthedocs.com",
+            }, {
+                "text": "Package",
+                "link": "https://pypi.com/sphinx-nefertiti",
+            }, {
+                "text": "Repository",
+                "link": "https://github.com/danirus/sphinx-nefertiti",
+            }, {
+                "text": "Issues",
+                "link": "https://github.com/danirus/sphinx-nefertiti/issues",
+            }
+        ]
     }
 
 In addition you can remove the **Built with Sphinx and Nefertiti** notice by setting the ``show_powered_by`` key to ``False``. It is ``True`` by default:

diff --git a/docs/source/users-guide/customization/version-dropdown.rst b/docs/source/users-guide/customization/version-dropdown.rst
@@ -5,9 +5,7 @@ Version dropdown
 
 If your Sphinx documentation is available for more than one version of your project, Nefertiti for Sphinx can display a dropdown in the header to switch between each of the documentation sites.
 
-If you use readthedocs_ to host your documentation and it serves multiple versions, Nefertiti will include them automatically in the Version dropdown. There is no need to add anything else.
-
-In any case, to see the version dropdown, whether in production or development, add the list of versions with their links to the ``conf.py`` file.
+To see the version dropdown, whether in production or development, add the list of versions with their links to the ``conf.py`` file.
 
 Theme options
 =============
@@ -26,7 +24,9 @@ Two theme options have to be provided in order to display the version dropdown:
     :width: 250
     :class: border-radius-2
 
-The ``current_version`` entry in ``html_theme_options`` represents the label displayed in the dropdown widget. In the right side image, the label ``3.13.0``.
+The ``current_version`` entry in ``html_theme_options`` represents the label displayed in the dropdown widget.
+
+The image in the right shows the label ``3.13.0`` as provided to the option ``current_version``.
 
 
 2. ``versions``
@@ -88,6 +88,3 @@ Save the previous changes and rebuild your Sphinx site:
     $ python -m http.server -d build/html
 
 Visit http://localhost:8000 to take a look at the changes.
-
-
-.. _readthedocs: https://readthedocs.org
diff --git a/js/src/versions.js b/js/src/versions.js
@@ -9,7 +9,7 @@ function _getCurrentVersion() {
       return version_elem.dataset?.snfttVersion;
     };
   }
-  return "";
+  return globalThis.def_ver || "";
 }
 
 export function updateVersion() {
@@ -42,7 +42,7 @@ export function feedVersionsMenu() {
   // Use the variable 'docs_versions' loaded as a script in layout.html.
   // The file docs_versions.js is produced by versions.py when building
   // the site (make html).
-  for (const item of docs_versions) {
+  for (const item of globalThis.docs_versions) {
     const li = document.createElement("li");
     const anchor = document.createElement("a");
     anchor.classList.add(

diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "sphinx-nefertiti",
-  "version": "0.5.2",
+  "version": "0.5.3",
   "private": true,
   "description": "Nefertiti is a theme for the Sphinx Documentation Generator.",
   "engines": {

diff --git a/sphinx_nefertiti/__init__.py b/sphinx_nefertiti/__init__.py
@@ -6,7 +6,7 @@
 
 from sphinx_nefertiti import colorsets, docsver, fonts, links, pygments
 
-__version__ = "0.5.2"
+__version__ = "0.5.3"
 
 pages_wo_index = ["genindex", "search"]
 
@@ -62,7 +62,10 @@ def initialize_theme(app):
     docs_versions_script = "docs-versions.js"
     docs_versions_path = dest_dir / docs_versions_script
     with docs_versions_path.open("w") as f:
-        f.write("const docs_versions = " + json.dumps(app.all_docs_versions))
+        versions_value = json.dumps(app.all_docs_versions)
+        f.write(f"window.docs_versions = {versions_value};\n")
+        if docsver_provider.current_version is not None:
+            f.write(f"window.def_ver = '{docsver_provider.current_version}';")
     app.add_js_file(docs_versions_script)
     app.add_js_file("sphinx-nefertiti.min.js")
     app.add_js_file("bootstrap.bundle.min.js")

diff --git a/sphinx_nefertiti/docsver.py b/sphinx_nefertiti/docsver.py
@@ -1,5 +1,6 @@
 class DocsVersionProvider:
     def __init__(self, app):
+        self.current_version = None
         theme_user_prefs = app.config.html_theme_options
 
         self._index = -1
@@ -8,6 +9,8 @@ def __init__(self, app):
         if "versions" not in theme_user_prefs:
             return
 
+        self.current_version = theme_user_prefs.get("current_version", None)
+
         for name, url in theme_user_prefs["versions"]:
             self._assets.append({"name": name, "url": url})