Wip to fix issues building 5.0 (in RTD) (#43)

* Wip to fix issues building 5.0 (in RTD)
* Remove nefertiti from extensions
* Add 'sphinx_nefertiti' as an extension
* Prepare release 0.5.1
* Fix issue when selecting active header link

.readthedocs.yaml

@@ -7,7 +7,10 @@ build:
 
 python:
   install:
-    - requirements: docs-deps.txt
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs
 
 sphinx:
   configuration: docs/source/conf.py

ChangeLog.md

@@ -1,6 +1,11 @@
 # Change Log
 
-## [0.5.0] - Unreleased
+## [0.5.1] - Unreleased
+
+- Header and footer links can be references to internal documents or URLs.
+- Fix issue in Nefertiti when building the docs in ReadTheDocs.
+
+## [0.5.0] - 2024-11-25
 
 - Add breadcrumbs.
 - Use smooth scrolling.

docs/source/conf.py

@@ -45,6 +45,7 @@
     'sphinx_design',
     'sphinx_copybutton',
     'sphinx_colorschemed_images',
+    'sphinx_nefertiti'
 ]
 
 myst_enable_extensions = [
@@ -101,39 +102,39 @@
     "header_links": [
         {
             "text" : "Quick Start",
-            "link": "/quick-start.html",
+            "link": "quick-start",
         },
         {
             "text": "Customize",
-            "match": "^/users-guide/customization/*",
+            "match": "/users-guide/customization/*",
             "dropdown": (
                 {
                     "text": "Fonts",
-                    "link": "/users-guide/customization/fonts.html"
+                    "link": "users-guide/customization/fonts"
                 },
                 {
                     "text": "Colorsets",
-                    "link": "/users-guide/customization/colorsets.html"
+                    "link": "users-guide/customization/colorsets"
                 },
                 {
                     "text": "Header Links",
-                    "link": "/users-guide/customization/header-links.html"
+                    "link": "users-guide/customization/header-links"
                 },
                 {
                     "text": "Footer Links",
-                    "link": "/users-guide/customization/footer-links.html"
+                    "link": "users-guide/customization/footer-links"
                 },
                 {
                     "text": "Version Dropdown",
-                    "link": "/users-guide/customization/version-dropdown.html"
+                    "link": "users-guide/customization/version-dropdown"
                 },
                 {
                     "text": "Git Repository",
-                    "link": "/users-guide/customization/git-repository.html"
+                    "link": "users-guide/customization/git-repository"
                 },
                 {
                     "text": "Pygments",
-                    "link": "/users-guide/customization/pygments.html"
+                    "link": "users-guide/customization/pygments"
                 },
                 {
                     "divider": True
@@ -146,7 +147,7 @@
         },
         {
             "text": "Release Notes",
-            "link": "/release-notes.html",
+            "link": "release-notes",
         }
     ],
 

docs/source/users-guide/customization/colorsets.rst

@@ -88,6 +88,10 @@ Test the different colorsets using the palette dropdown in the header. You can a
         # "reset_colorset_choice_after_ms": 0,
     }
 
+.. important::
+
+    When adding ``"show_colorset_choices": True`` and building in ReadTheDocs, be sure to add ``sphinx_nefertiti`` as an extension.
+
 
 The ``style`` setting
 *********************

docs/source/users-guide/customization/footer-links.rst

@@ -36,7 +36,7 @@ The content for the ``footer_links`` is a list of dictionaries with the format:
     [
         {
             'text': '<the label to display>',
-            'link': '<the target URL>',
+            'link': '<toctree-doc-path | URL>',
         },
     ]
 
@@ -54,13 +54,13 @@ A valid footer links could be:
         "footer_links": [
             {
                 'text': 'Home',
-                'link': '/',
+                'link': 'index',
             }, {
                 'text': 'Documentation',
-                'link': '/docs',
+                'link': 'https://myproject.org/docs',
             }, {
                 'text': 'Code',
-                'link': '/code',
+                'link': 'https://your.git.host/code',
             },
         ],
 

docs/source/users-guide/customization/header-links.rst

@@ -55,15 +55,21 @@ The ``html_theme_options`` setting in Nefertiti for Sphinx can have two entries
 
 Header links can be either actual links or dropdown elements. Each header link may contain a ``text``, a ``link`` and an optional ``match``:
 
+* ``text``: a string.
+* ``link``: a document path in Sphinx or a URL.
+* ``match``: a string or list or strings, used as JavaScript Regular Expressions.
+
+An example:
+
 .. code-block:: python
 
     html_theme_options = {
         # ... other options ...
         "header_links": [
             {
                 "text": "Examples",
-                "link": "/examples/index.html",
-                "match": "^/examples/*",
+                "link": "examples/index",
+                "match": "/examples/*",
             },
         ],
     }
@@ -97,11 +103,11 @@ The following ``header_links``, added to the ``html_theme_options`` setting of a
     'header_links': [
         {
             'text': 'Home',
-            'link': '/',
+            'link': 'index',
         },
         {
             'text': 'Tutorial',
-            'link': '/tutorial.html',
+            'link': 'tutorial',
         },
         {
             'text': 'Blog',
@@ -151,7 +157,7 @@ You could add an entry **Learn** to your header with a header link like:
         # ... other header links ...
         {
             'text': 'Learn',
-            'link': '/learn/index.html',
+            'link': 'learn/index',
             'match': [
                 '/learn/*',
                 '/python-types.html',
@@ -182,21 +188,21 @@ If you wanted to reproduced the previous ``toctree`` as a dropdown menu in the h
             "dropwdown": (
                 {
                     "text": "Learn",
-                    "link": "/learn/index.html",
+                    "link": "learn/index",
                 }, {
                     "text": "Python Types Intro",
-                    "link": "/python-types.html",
+                    "link": "python-types",
                 }, {
                     "text": "Concurrency and async/await",
-                    "link": "async.html",
+                    "link": "async",
                 }, {
                     "divider": True,
                 }, {
                     "text": "Tutorial - User Guide",
-                    "link": "/tutorial/index.html",
+                    "link": "tutorial/index",
                 }, {
                     "text": "Advanced User Guide",
-                    "link": "/advanced/index.html",
+                    "link": "advanced/index",
                 }
             )
         }
@@ -216,7 +222,7 @@ If you wanted to reproduced the previous ``toctree`` as a dropdown menu in the h
 
 Dropdowns can also include Regular Expressions by adding a ``match`` to the item inside the dropdown.
 
-Following up on the previous example, if the tutorial had more documents, we would be able to paginate following the links at the bottom of the page. However, by doing so, the dropdown "Learn" would lose the active state, as the URL of the documents inside the tutorial would not match the ``"link": "/tutorial/index.html"``:
+Following up on the previous example, if the tutorial had more documents, we would be able to paginate following the links at the bottom of the page. However, by doing so, the dropdown "Learn" would lose the active state, as the URL of the documents inside the tutorial would not match the ``"link": "tutorial/index"``:
 
 .. cs_figure:: img/rhythm-header-learn-dropdown-loses-active.*
     :alt: The dropdown loses the active state.
@@ -237,22 +243,22 @@ Adding the following ``match`` to the Tutorial item inside the dropdown will hav
             "dropwdown": (
                 {
                     "text": "Learn",
-                    "link": "/learn/index.html",
+                    "link": "learn/index",
                 }, {
                     "text": "Python Types Intro",
-                    "link": "/python-types.html",
+                    "link": "python-types",
                 }, {
                     "text": "Concurrency and async/await",
-                    "link": "async.html",
+                    "link": "async",
                 }, {
                     "divider": True,
                 }, {
                     "text": "Tutorial - User Guide",
-                    "link": "/tutorial/index.html",
-                    "match": "^/tutorial/*",
+                    "link": "tutorial/index",
+                    "match": "/tutorial/*",
                 }, {
                     "text": "Advanced User Guide",
-                    "link": "/advanced/index.html",
+                    "link": "advanced/index",
                 }
             )
         }

js/src/navbar.js

@@ -23,19 +23,14 @@ export function selectActiveHeaderLink() {
     elem.ariaCurrent = false;
   }
 
-  let qs = `.snftt-hl[href='${curl.pathname}']`;
-  let elements = document.querySelectorAll(qs);
-  for (const elem of elements) {
-    _addActiveCssClass(elem);
+  // Activate the current link:
+  let qs = `.snftt-hl[href='#']`;
+  for (const elem of document.querySelectorAll(qs)) {
+    if (!elem.classList.contains("dropdown-toggle")) {
+      _addActiveCssClass(elem);
+    }
   }
 
-  // If there are elements, it means a header-link has been found with
-  // the exact same pathname as the one the user is browsing. There has
-  // to be several elements because the header-links are in two HTML
-  // classes, nftt-header-links-large and nftt-header-links-small.
-  if (elements.length > 0)
-    return;
-
   // Find header-link element (.snftt-hl) with regexps, and
   // check whether the current pathname matches the regexp.
   let hl_id = 0;  // Not found.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "sphinx-nefertiti",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "private": true,
   "description": "Nefertiti is a theme for the Sphinx Documentation Generator.",
   "engines": {

pyproject.toml

@@ -55,7 +55,7 @@ docs = [
     "sphinx-colorschemed-images >=0.2.0",
     "sphinx_copybutton >=0.5.2, <1.0.0",
     "sphinx-design >=0.6.1, <0.7",
-    "sphinx-nefertiti",
+    "sphinx-nefertiti >=0.5.0",
 ]
 
 [tool.setuptools]

sphinx_nefertiti/__init__.py

@@ -4,16 +4,12 @@
 import shutil
 from pathlib import Path
 
-from sphinx.util import logging
-
 from sphinx_nefertiti import colorsets, docsver, fonts, links, pygments
 
-__version__ = "0.5.0"
+__version__ = "0.5.1"
 
 pages_wo_index = ["genindex", "search"]
 
-logger = logging.getLogger(__name__)
-
 
 def get_html_theme_path():
     """Return absolute path to parent folder of installed theme."""
@@ -80,17 +76,9 @@ def update_context(app, pagename, templatename, context, doctree):
     context["all_colorsets"] = colorsets.all_colorsets
 
 
-def build_finished(app, exc):
-    logger.info(f"Files in {app.builder.outdir}")
-    static_dir = Path(app.builder.outdir) / "_static"
-    for item in static_dir.iterdir():
-        logger.info(f" - {item}")
-
-
 def setup(app):
     app.connect("builder-inited", initialize_theme)
     app.connect("html-page-context", update_context)
-    app.connect("build-finished", build_finished)
 
     if hasattr(app, "add_html_theme"):
         theme_path = str(Path(__file__).parent)

sphinx_nefertiti/footer.html

@@ -6,7 +6,7 @@
       <ul id="nftt-footer-links" class="list-unstyled list-separator col-lg-12 pb-2 text-center">
         {% for item in footer_links %}
           <li class="d-inline">
-            <a href="{{ item.link }}" class="list-item">{{ item.text }}</a>
+            <a href="{{ pathto(item.link, item.resource) }}" class="list-item">{{ item.text }}</a>
           </li>
         {% endfor %}
       </ul>

sphinx_nefertiti/header-links.html

@@ -15,7 +15,7 @@
     <li><hr class="dropdown-divider"></li>
   {% elif "text" in link_item and "link" in link_item %}
     <li {% if li_class %}class="{{ li_class }}"{% endif %}>
-      <a {% if a_class %}class="snftt-hl {{ a_class }}"{% endif %} href="{{ link_item.link }}" data-snftt-hl-id="{{ link_item.hlid }}" {% if 'match' in link_item %}data-snftt-hl-id="{{ link_item.id }}" data-snftt-hl-regexps="{{ link_item.match|join('&&') }}"{% endif %}>{{ link_item.text }}</a>
+      <a {% if a_class %}class="snftt-hl {{ a_class }}"{% endif %} href="{{ pathto(link_item.link, link_item.resource) }}" data-snftt-hl-id="{{ link_item.hlid }}" {% if 'match' in link_item %}data-snftt-hl-id="{{ link_item.id }}" data-snftt-hl-regexps="{{ link_item.match|join('&&') }}"{% endif %}>{{ link_item.text }}</a>
     </li>
   {% endif %}
 {% endfor %}

sphinx_nefertiti/links.py

@@ -100,6 +100,10 @@ def _validate_dropdown(self, dropdown_elem: tuple):
             self._urls.add(dd_item["link"])
             self._hlid += 1
             dd_item["hlid"] = self._hlid
+            if "://" in dd_item["link"]:
+                dd_item["resource"] = True
+            else:
+                dd_item["resource"] = False
         self._links.append(dropdown_elem)
 
     def _validate(self):
@@ -144,6 +148,10 @@ def _validate(self):
             self._urls.add(item["link"])
             self._hlid += 1
             item["hlid"] = self._hlid
+            if "://" in item["link"]:
+                item["resource"] = True
+            else:
+                item["resource"] = False
             self._links.append(item)
 
     def __iter__(self):
@@ -202,6 +210,10 @@ def _validate(self):
                 )
 
             self._urls.add(item["link"])
+            if "://" in item["link"]:
+                item["resource"] = True
+            else:
+                item["resource"] = False
             self._links.append(item)
 
     def __iter__(self):