From 6bd8ca7bd872941fc6126f851fd8bc609b0c1927 Mon Sep 17 00:00:00 2001 From: Daniela Rus Morales <157103+danirus@users.noreply.github.com> Date: Thu, 28 Nov 2024 13:17:57 +0100 Subject: [PATCH] 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 --- ChangeLog.md | 6 + docs/source/conf.py | 28 ++-- docs/source/quick-start.rst | 125 ++++++++++++++---- .../customization/version-dropdown.rst | 11 +- js/src/versions.js | 4 +- package.json | 2 +- sphinx_nefertiti/__init__.py | 7 +- sphinx_nefertiti/docsver.py | 3 + .../static/sphinx-nefertiti.min.js | 4 +- .../static/sphinx-nefertiti.min.js.map | 2 +- sphinx_nefertiti/version-dropdown.html | 60 ++------- tests/test_sample_projects.py | 4 +- 12 files changed, 153 insertions(+), 103 deletions(-) diff --git a/ChangeLog.md b/ChangeLog.md index f23dd8e..3b2b134 100644 --- 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 index 453f176..8f84c36 100644 --- 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 index 2b9eb49..2e1fc53 100644 --- 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,19 +227,17 @@ 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: ``"|"``. +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: @@ -183,12 +245,21 @@ As an example, the 4 links of the current Nefertiti for Sphinx documentation loo 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 index ff3e0bf..54b2967 100644 --- 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 index 36001e9..d1c9a74 100644 --- 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 index ee5be5e..59f9804 100644 --- 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 index 736011e..fc95b98 100644 --- 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 index 037a7ef..28fb03b 100644 --- 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}) diff --git a/sphinx_nefertiti/static/sphinx-nefertiti.min.js b/sphinx_nefertiti/static/sphinx-nefertiti.min.js index 4509fca..4d1c498 100644 --- a/sphinx_nefertiti/static/sphinx-nefertiti.min.js +++ b/sphinx_nefertiti/static/sphinx-nefertiti.min.js @@ -1,7 +1,7 @@ function _arrayLikeToArray$1(e,t){(null==t||t>e.length)&&(t=e.length);for(var r=0,n=Array(t);r=e.length?{done:!0}:{done:!1,value:e[n++]}}}throw new TypeError("Invalid attempt to iterate non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method.")}function _regeneratorRuntime(){_regeneratorRuntime=function(){return t};var e,t={},r=Object.prototype,n=r.hasOwnProperty,o=Object.defineProperty||function(e,t,r){e[t]=r.value},a="function"==typeof Symbol?Symbol:{},i=a.iterator||"@@iterator",s=a.asyncIterator||"@@asyncIterator",c=a.toStringTag||"@@toStringTag";function l(e,t,r){return Object.defineProperty(e,t,{value:r,enumerable:!0,configurable:!0,writable:!0}),e[t]}try{l({},"")}catch(e){l=function(e,t,r){return e[t]=r}}function u(e,t,r,n){var a=t&&t.prototype instanceof g?t:g,i=Object.create(a.prototype),s=new T(n||[]);return o(i,"_invoke",{value:A(e,r,s)}),i}function d(e,t,r){try{return{type:"normal",arg:e.call(t,r)}}catch(e){return{type:"throw",arg:e}}}t.wrap=u;var f="suspendedStart",p="suspendedYield",v="executing",h="completed",m={};function g(){}function y(){}function _(){}var b={};l(b,i,(function(){return this}));var L=Object.getPrototypeOf,w=L&&L(L(H([])));w&&w!==r&&n.call(w,i)&&(b=w);var S=_.prototype=g.prototype=Object.create(b);function x(e){["next","throw","return"].forEach((function(t){l(e,t,(function(e){return this._invoke(t,e)}))}))}function E(e,t){function r(o,a,i,s){var c=d(e[o],e,a);if("throw"!==c.type){var l=c.arg,u=l.value;return u&&"object"==typeof u&&n.call(u,"__await")?t.resolve(u.__await).then((function(e){r("next",e,i,s)}),(function(e){r("throw",e,i,s)})):t.resolve(u).then((function(e){l.value=e,i(l)}),(function(e){return r("throw",e,i,s)}))}s(c.arg)}var a;o(this,"_invoke",{value:function(e,n){function o(){return new t((function(t,o){r(e,n,t,o)}))}return a=a?a.then(o,o):o()}})}function A(t,r,n){var o=f;return function(a,i){if(o===v)throw Error("Generator is already running");if(o===h){if("throw"===a)throw i;return{value:e,done:!0}}for(n.method=a,n.arg=i;;){var s=n.delegate;if(s){var c=I(s,n);if(c){if(c===m)continue;return c}}if("next"===n.method)n.sent=n._sent=n.arg;else if("throw"===n.method){if(o===f)throw o=h,n.arg;n.dispatchException(n.arg)}else"return"===n.method&&n.abrupt("return",n.arg);o=v;var l=d(t,r,n);if("normal"===l.type){if(o=n.done?h:p,l.arg===m)continue;return{value:l.arg,done:n.done}}"throw"===l.type&&(o=h,n.method="throw",n.arg=l.arg)}}}function I(t,r){var n=r.method,o=t.iterator[n];if(o===e)return r.delegate=null,"throw"===n&&t.iterator.return&&(r.method="return",r.arg=e,I(t,r),"throw"===r.method)||"return"!==n&&(r.method="throw",r.arg=new TypeError("The iterator does not provide a '"+n+"' method")),m;var a=d(o,t.iterator,r.arg);if("throw"===a.type)return r.method="throw",r.arg=a.arg,r.delegate=null,m;var i=a.arg;return i?i.done?(r[t.resultName]=i.value,r.next=t.nextLoc,"return"!==r.method&&(r.method="next",r.arg=e),r.delegate=null,m):i:(r.method="throw",r.arg=new TypeError("iterator result is not an object"),r.delegate=null,m)}function k(e){var t={tryLoc:e[0]};1 in e&&(t.catchLoc=e[1]),2 in e&&(t.finallyLoc=e[2],t.afterLoc=e[3]),this.tryEntries.push(t)}function O(e){var t=e.completion||{};t.type="normal",delete t.arg,e.completion=t}function T(e){this.tryEntries=[{tryLoc:"root"}],e.forEach(k,this),this.reset(!0)}function H(t){if(t||""===t){var r=t[i];if(r)return r.call(t);if("function"==typeof t.next)return t;if(!isNaN(t.length)){var o=-1,a=function r(){for(;++o=0;--a){var i=this.tryEntries[a],s=i.completion;if("root"===i.tryLoc)return o("end");if(i.tryLoc<=this.prev){var c=n.call(i,"catchLoc"),l=n.call(i,"finallyLoc");if(c&&l){if(this.prev=0;--r){var o=this.tryEntries[r];if(o.tryLoc<=this.prev&&n.call(o,"finallyLoc")&&this.prev=0;--t){var r=this.tryEntries[t];if(r.finallyLoc===e)return this.complete(r.completion,r.afterLoc),O(r),m}},catch:function(e){for(var t=this.tryEntries.length-1;t>=0;--t){var r=this.tryEntries[t];if(r.tryLoc===e){var n=r.completion;if("throw"===n.type){var o=n.arg;O(r)}return o}}throw Error("illegal catch attempt")},delegateYield:function(t,r,n){return this.delegate={iterator:H(t),resultName:r,nextLoc:n},"next"===this.method&&(this.arg=e),m}},t}function _taggedTemplateLiteralLoose(e,t){return t||(t=e.slice(0)),e.raw=t,e}function _toPrimitive(e,t){if("object"!=typeof e||!e)return e;var r=e[Symbol.toPrimitive];if(void 0!==r){var n=r.call(e,t);if("object"!=typeof n)return n;throw new TypeError("@@toPrimitive must return a primitive value.")}return String(e)}function _toPropertyKey(e){var t=_toPrimitive(e,"string");return"symbol"==typeof t?t:t+""}function _unsupportedIterableToArray$1(e,t){if(e){if("string"==typeof e)return _arrayLikeToArray$1(e,t);var r={}.toString.call(e).slice(8,-1);return"Object"===r&&e.constructor&&(r=e.constructor.name),"Map"===r||"Set"===r?Array.from(e):"Arguments"===r||/^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(r)?_arrayLikeToArray$1(e,t):void 0}}var BACK_TO_TOP_BUTTON_ID="back-to-top",BACK_TO_TOP_DIV_ID="back-to-top-container",NAVBAR_ID="snftt-nav-bar",DEFAULT_NAVBAR_HEIGHT=60,BackToTop=function(){var e=this;this._scrollHandler=function(t){var r=window.pageYOffset||document.documentElement.scrollTop;r>e.prev_offset||r<=e.navbar_height?e.btn.classList.add("d-none"):re.navbar_height&&e.btn.classList.remove("d-none"),e.prev_offset=r<=0?0:r},this._scrollToTopHandler=function(e){e.preventDefault(),document.documentElement.scrollTop=0},this.init=function(){window.addEventListener("scroll",e._scrollHandler,!1),e.btn.addEventListener("click",e._scrollToTopHandler,!1)},this.btn=document.getElementById(BACK_TO_TOP_BUTTON_ID),this.prev_offset=0;var t=document.getElementById(NAVBAR_ID);this.navbar_height=t.offsetHeight||DEFAULT_NAVBAR_HEIGHT,document.getElementById(BACK_TO_TOP_DIV_ID).style.top=this.navbar_height+16+"px"},FIGURE_IMG_SELECTOR="#content figure";function fixFigureStyle(){for(var e,t=_createForOfIteratorHelperLoose$1(document.querySelectorAll(FIGURE_IMG_SELECTOR));!(e=t()).done;){var r=e.value,n=r.querySelector("img");if(n&&n.style&&(n.style.width||n.style.height)){var o=n.width;r.style.width=o+"px";var a=r.querySelector("figcaption");a&&(a.style.width=o+"px"),n.style.width&&(n.style.width="")}}} /*! - * sphinx-colorschemed-images v0.2.0 (https://github.com/danirus/sphinx-colorschemed-images). + * sphinx-colorschemed-images v0.2.2 (https://github.com/danirus/sphinx-colorschemed-images). * Copyright 2024 Daniela Rus Morales. * Licensed under MIT (https://github.com/danirus/sphinx-colorschemed-images/blob/main/LICENSE). - */function _arrayLikeToArray(e,t){(null==t||t>e.length)&&(t=e.length);for(var r=0,n=Array(t);r=e.length?{done:!0}:{done:!1,value:e[n++]}}}throw new TypeError("Invalid attempt to iterate non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method.")}function _unsupportedIterableToArray(e,t){if(e){if("string"==typeof e)return _arrayLikeToArray(e,t);var r={}.toString.call(e).slice(8,-1);return"Object"===r&&e.constructor&&(r=e.constructor.name),"Map"===r||"Set"===r?Array.from(e):"Arguments"===r||/^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(r)?_arrayLikeToArray(e,t):void 0}}var SphinxColorschemeImageHandler=function(e){var t=this;void 0===e&&(e={}),this.activate=function(e){for(var t,r="data-alt-src-color-scheme-"+e,n=function(){var e=t.value,n=new Image,o=e.getAttribute(r);n.src=o,n.addEventListener("load",(function(){e.src=n.src})),n.addEventListener("error",(function(){console.error("Could not replace image "+e.src+" with "+o+".")})),n.complete&&(e.src=n.src);var a=e.closest("figure");if(null!=a){var i=a.querySelector("a");i.getAttribute("href")!==o&&(i.href=o)}else"A"==e.parentElement.tagName&&e.parentElement.getAttribute("href")!==o&&(e.parentElement.href=e.getAttribute(r))},o=_createForOfIteratorHelperLoose(document.querySelectorAll("img["+r+"]"));!(t=o()).done;)n()},this._schemes=[],this._mediaqs=[],this._auto=!e.hasOwnProperty("auto")||!0===e.auto;var r=document.querySelector('meta[name="color-scheme"]'),n=null==r?"":r.content;if(n.length>0)for(var o,a=_createForOfIteratorHelperLoose(n.split(" "));!(o=a()).done;){var i=o.value;this._schemes.push(i.trim())}else this._schemes=["light","dark"];for(var s,c=function(){var e=s.value,r=globalThis.matchMedia("(prefers-color-scheme: "+e+")");r.matches&&t.activate(e),!0===t._auto&&(r.addEventListener("change",(function(r){r.matches&&t.activate(e)})),t._mediaqs.push(r))},l=_createForOfIteratorHelperLoose(this._schemes);!(s=l()).done;)c()},CSchemeHandler=function(){function e(){var e=this;this.stored=localStorage.getItem("snftt-color-scheme")||"default",this._cshdl=new SphinxColorschemeImageHandler({auto:!1});for(var t=function(){var t=n[r],o=globalThis.matchMedia("(prefers-color-scheme: "+t+")");o.matches&&"default"==e.stored&&(e.apply(t),e.updateDropdown(e.stored),e._cshdl.activate(t)),o.addEventListener("change",(function(r){r.matches&&(e.apply(t),e._cshdl.activate(t))}))},r=0,n=["dark","light"];r-1&&(e.refs.splice(r,1),localStorage.setItem("toc-expanded",e.refs.join(",")))},this._expandRefs=function(){for(var t,r=_createForOfIteratorHelperLoose$1(e.refs);!(t=r()).done;){var n=t.value,o=e.toc.querySelector("li[data-snftt-ref='"+n+"']");null!=o?o.classList.contains("expand")||(o.classList.toggle("expand"),e._updateItem(o)):e._removeRef(n)}},this._expandOrFoldAll=function(t){void 0===t&&(t=!0);for(var r,n=_createForOfIteratorHelperLoose$1(e.toc?e.toc.querySelectorAll("a.reference"):[]);!(r=n()).done;){var o=r.value;if(o.nextElementSibling){var a=o.parentElement;t?a.classList.add("expand"):a.classList.remove("expand"),e._updateItem(a,!1)}}},this._updateItem=function(t,r){void 0===r&&(r=!0);var n=t.querySelector("i");t.classList.contains("expand")?(n.classList.remove("bi-caret-right"),n.classList.add("bi-caret-down"),r&&!e.refs.includes(t.dataset.snfttRef)&&(e.refs.push(t.dataset.snfttRef),localStorage.setItem("toc-expanded",e.refs.join(",")))):(n.classList.remove("bi-caret-down"),n.classList.add("bi-caret-right"),r&&e.refs.includes(t.dataset.snfttRef)&&e._removeRef(t.dataset.snfttRef))},this._clickHandler=function(t){var r=t.currentTarget,n=null==r?void 0:r.parentElement;n.classList.toggle("expand"),e._updateItem(n)},this._keyupHandler=function(t){var r=e.toc.querySelectorAll("ul"),n=e.toc.querySelectorAll("a.reference");if(0===e.filter.value.length){for(var o,a=_createForOfIteratorHelperLoose$1(n);!(o=a()).done;){var i;null==(i=o.value.parentElement)||i.classList.remove("d-none")}for(var s,c=_createForOfIteratorHelperLoose$1(r);!(s=c()).done;)s.value.classList.remove("d-none");return e._expandOrFoldAll(!1),void e._expandRefs()}for(var l,u=_createForOfIteratorHelperLoose$1(n);!(l=u()).done;){var d;null==(d=l.value.parentElement)||d.classList.add("d-none")}for(var f,p=_createForOfIteratorHelperLoose$1(r);!(f=p()).done;)f.value.classList.add("d-none");e._expandOrFoldAll(!0);for(var v,h=new RegExp(e.filter.value,"i"),m=_createForOfIteratorHelperLoose$1(n);!(v=m()).done;){var g,y=v.value;if(h.test(y.textContent))for(var _=y,b=null==(g=_)?void 0:g.parentElement;_;){var L,w;_.classList.remove("d-none"),"UL"===(b=_.parentElement).nodeName&&(null==(w=b)||w.classList.remove("d-none")),_=null==(L=b)?void 0:L.closest("li")}}},this.init=function(){var t=0;e.toc=document.querySelector(".toc"),e.filter=e.toc.querySelector("input[name='filter']"),e.refs=loadRefList();var r=e.toc?e.toc.querySelectorAll("a.reference"):[],n=document.querySelector(TEMPLATE_SELECTOR),o=null==n?void 0:n.content.firstElementChild;if(null==o)return-1;e.filter.addEventListener("keyup",e._keyupHandler);for(var a,i=_createForOfIteratorHelperLoose$1(r);!(a=i()).done;){var s=a.value;if(s.nextElementSibling){var c=o.cloneNode(!0);c.addEventListener("click",e._clickHandler,!0),s.before(c);var l=s.parentElement;l.dataset.snfttRef=s.href,l&&l.classList.contains("current")&&(l.classList.toggle("current"),l.classList.toggle("expand"),e._updateItem(l)),t++}}return e._expandRefs(),t},this.toc,this.refs,this.filter};function _addActiveCssClass(e){if(e.classList.add("active"),e.ariaCurrent=!0,e.classList.contains("dropdown-item")){var t=e.closest("li.nav-item.dropdown");if(!t)return;var r=t.querySelector("a.nav-link.dropdown-toggle");if(!r)return;r&&(r.classList.add("active"),r.ariaCurrent=!0)}}function selectActiveHeaderLink(){for(var e,t=URL.parse(window.location.href),r=_createForOfIteratorHelperLoose$1(document.querySelectorAll(".snftt-hl"));!(e=r()).done;){var n=e.value;n.classList.remove("active"),n.ariaCurrent=!1}for(var o,a=".snftt-hl[href='#']",i=_createForOfIteratorHelperLoose$1(document.querySelectorAll(a));!(o=i()).done;){var s=o.value;s.classList.contains("dropdown-toggle")||_addActiveCssClass(s)}var c=0;a=".nftt-header-links-large .snftt-hl[data-snftt-hl-regexps]";for(var l,u=_createForOfIteratorHelperLoose$1(document.querySelectorAll(a));!(l=u()).done;)for(var d,f=l.value,p=_createForOfIteratorHelperLoose$1(f.dataset.snfttHlRegexps.split("&&"));!(d=p()).done;){var v=d.value;if(new RegExp(v).test(t.pathname)){c=f.dataset.snfttHlId;break}}if(0!=c){a=".snftt-hl[data-snftt-hl-id='"+c+"']";for(var h,m=_createForOfIteratorHelperLoose$1(document.querySelectorAll(a));!(h=m()).done;)_addActiveCssClass(h.value)}}function formatNumber(e){var t=document.documentElement.lang||"en";return e.toLocaleString(t,{maximumFractionDigits:2,notation:"compact",compactDisplay:"short"})}function readFromGitHub(e,t){return _readFromGitHub.apply(this,arguments)}function _readFromGitHub(){return(_readFromGitHub=_asyncToGenerator(_regeneratorRuntime().mark((function e(t,r){var n,o,a,i,s,c,l,u;return _regeneratorRuntime().wrap((function(e){for(;;)switch(e.prev=e.next){case 0:return n="",o="",a="",i="https://api.github.com/repos/"+t+"/"+r,e.next=6,fetch(i);case 6:if(200===(s=e.sent).status){e.next=9;break}throw new Error("Rate limit reached.");case 9:return e.next=11,s.json();case 11:return c=e.sent,o=formatNumber(c.stargazers_count),localStorage.setItem(t+":"+r+":stars",o),a=formatNumber(c.forks_count),localStorage.setItem(t+":"+r+":forks",a),e.next=18,fetch(i+"/releases/latest");case 18:if(200===(l=e.sent).status){e.next=21;break}throw new Error("Rate limit reached.");case 21:return e.next=23,l.json();case 23:if(u=e.sent,n=u.tag_name,localStorage.setItem(t+":"+r+":tag",n),""===n||""==o||""==a){e.next=28;break}return e.abrupt("return",{tag:n,stars:o,forks:a});case 28:case"end":return e.stop()}}),e)})))).apply(this,arguments)}function readFromGitLab(e,t){return _readFromGitLab.apply(this,arguments)}function _readFromGitLab(){return(_readFromGitLab=_asyncToGenerator(_regeneratorRuntime().mark((function e(t,r){var n,o,a,i,s;return _regeneratorRuntime().wrap((function(e){for(;;)switch(e.prev=e.next){case 0:return n="",o="",a="https://"+t+"/api/v4/projects/"+encodeURIComponent(r),e.next=5,fetch(a);case 5:if(200===(i=e.sent).status){e.next=8;break}throw new Error("Rate limit reached.");case 8:return e.next=10,i.json();case 10:if(s=e.sent,n=formatNumber(s.star_count),localStorage.setItem(t+":"+r+":stars",n),o=formatNumber(s.forks_count),localStorage.setItem(t+":"+r+":forks",o),""==n||""==o){e.next=17;break}return e.abrupt("return",{tag:"",stars:n,forks:o});case 17:case"end":return e.stop()}}),e)})))).apply(this,arguments)}var ls=localStorage,qs_repo_url="[data-snftt-repo-url]",qs_repo_facts="[data-snftt-repo-metrics]",qs_repo_tag="[data-snftt-repo-tag]",qs_repo_stars="[data-snftt-repo-stars]",qs_repo_forks="[data-snftt-repo-forks]";function _updateFactsComponent(e){var t=0,r=document.querySelector(qs_repo_facts),n=document.querySelector(qs_repo_tag),o=document.querySelector(qs_repo_stars),a=document.querySelector(qs_repo_forks);return null!=e.tag&&e.tag.length>0?(n.textContent=e.tag,t++):(n.parentElement.classList.remove("d-flex"),n.parentElement.classList.add("d-none")),null!=e.stars&&e.stars.length>0?(o.textContent=e.stars,t++):(o.parentElement.classList.remove("d-flex"),o.parentElement.classList.add("d-none")),null!=e.forks&&e.forks.length>0?(a.textContent=e.forks,t++):(a.parentElement.classList.remove("d-flex"),a.parentElement.classList.add("d-none")),r.classList.add("ready"),t}function _readFromLocalStorage(e,t){var r=ls.getItem(e+":"+t+":tag"),n=ls.getItem(e+":"+t+":stars"),o=ls.getItem(e+":"+t+":forks");return n&&o?{tag:r,stars:n,forks:o}:{tag:"",stars:"",forks:""}}function _getRepoMetrics(e,t,r){return _getRepoMetrics2.apply(this,arguments)}function _getRepoMetrics2(){return(_getRepoMetrics2=_asyncToGenerator(_regeneratorRuntime().mark((function e(t,r,n){var o,a,i,s;return _regeneratorRuntime().wrap((function(e){for(;;)switch(e.prev=e.next){case 0:if((a=ls.getItem(r+":"+n+":lastaccess"))&&(i=Date.now(),(s=new Date).setTime(Number.parseInt(a)+6e4),s.getTime()>i&&(o=_readFromLocalStorage(r,n))),o){e.next=21;break}e.prev=3,e.t0=t,e.next="github"===e.t0?7:"gitlab"===e.t0?11:15;break;case 7:return e.next=9,readFromGitHub(r,n);case 9:return o=e.sent,e.abrupt("break",15);case 11:return e.next=13,readFromGitLab(r,n);case 13:return o=e.sent,e.abrupt("break",15);case 15:localStorage.setItem(r+":"+n+":lastaccess",""+Date.now()),e.next=21;break;case 18:e.prev=18,e.t1=e.catch(3),o=_readFromLocalStorage(r,n);case 21:return e.abrupt("return",o);case 22:case"end":return e.stop()}}),e,null,[[3,18]])})))).apply(this,arguments)}function updateRepoMetrics(){return _updateRepoMetrics.apply(this,arguments)}function _updateRepoMetrics(){return(_updateRepoMetrics=_asyncToGenerator(_regeneratorRuntime().mark((function e(){var t,r,n,o,a,i,s,c,l,u;return _regeneratorRuntime().wrap((function(e){for(;;)switch(e.prev=e.next){case 0:if(t=document.querySelector(qs_repo_url),r=t?t.dataset.snfttRepoUrl:"",!(n=r.match(/^.+github\.com\/([^/]+)\/?([^/]+)?/i))){e.next=10;break}return o=n[1],a=n[2],e.next=7,_getRepoMetrics("github",o,a);case 7:if(!(i=e.sent)){e.next=10;break}return e.abrupt("return",_updateFactsComponent(i));case 10:if(!(s=r.match(/^.+?([^/]*gitlab[^/]+)\/(.+?)\/?$/i))){e.next=18;break}return c=s[1],l=s[2],e.next=15,_getRepoMetrics("gitlab",c,l);case 15:if(!(u=e.sent)){e.next=18;break}return e.abrupt("return",_updateFactsComponent(u));case 18:return e.abrupt("return",-1);case 19:case"end":return e.stop()}}),e)})))).apply(this,arguments)}var _templateObject,TocObserver=function(){var e=this;this._sectionsObservationHandler=function(t){t.map((function(t){var r=t.target,n=e.toc.querySelector("a[href='#"+r.id+"']"),o=null==n?void 0:n.parentElement;!0===t.isIntersecting?null==o||o.classList.add("active"):null==o||o.classList.remove("active")}))},this._initializeSectionsObserver=function(t){e.section_observer=new IntersectionObserver(e._sectionsObservationHandler,{root:void 0,rootMargin:t,threshold:[0,.25,.5,.75,1]});for(var r,n=_createForOfIteratorHelperLoose$1(e.doc.querySelectorAll(":scope section"));!(r=n()).done;){var o=r.value;e.section_observer.observe(o)}},this.init=function(){var t;if(e.doc=document.querySelector(".nftt-content"),e.toc=document.querySelector("#TableOfContents"),null==e.doc||null==e.toc)return-1;var r="-"+((null==(t=document.querySelector("header"))?void 0:t.offsetHeight)||0)+"px 0px 0px 0px",n=e.doc.querySelector("section a.headerlink"),o=e.toc.querySelector("a.reference[href='#']");null!=n&&null!=o&&o.setAttribute("href",n.getAttribute("href"));for(var a,i=_createForOfIteratorHelperLoose$1(e.toc.querySelectorAll("a.reference"));!(a=i()).done;)a.value.classList.remove("active");return e._initializeSectionsObserver(r),0},this.doc,this.toc,this.section_observer};function resizeAsides(){var e,t="",r=document.querySelector(".nftt-content"),n=document.querySelector(".nftt-sidebar"),o=document.getElementById("back-to-top-container"),a=document.querySelector(".nftt-toc"),i=null==(e=document.querySelector("header"))?void 0:e.offsetHeight;return 0==window.matchMedia("(min-width: 1200px)").matches?(null==n||n.setAttribute("style",""),null==a||a.setAttribute("style",""),""):(null!=r&&(t=(r.clientHeight>document.body.clientHeight?"height: calc(100vh - "+(i+40)+"px)":"height: "+r.clientHeight+"px")+"; top: "+(i+40)+"px;",null==n||n.setAttribute("style",t),null==a||a.setAttribute("style",t),null==o||o.setAttribute("style","top: "+(i+20)+"px")),t)}function updateScrollPaddingTop(){var e,t=-1,r=document.querySelector("html"),n=null==(e=r.querySelector("header"))?void 0:e.offsetHeight;return null!=n&&(t=n+24,r.setAttribute("style","scroll-padding-top: "+t+"px")),t}var qs_version_url="[data-snftt-version-url]";function _getCurrentVersion(){for(var e,t=_createForOfIteratorHelperLoose$1(document.querySelectorAll(qs_version_url));!(e=t()).done;){var r,n,o=e.value,a=null==(r=o.dataset)?void 0:r.snfttVersionUrl;if(a=a.replace("?",String.raw(_templateObject||(_templateObject=_taggedTemplateLiteralLoose(["?"],["\\?"])))),new RegExp(a).test(window.location.href))return null==(n=o.dataset)?void 0:n.snfttVersion}return""}function updateVersion(){for(var e,t=_getCurrentVersion(),r=document.querySelector("[data-snftt-version-active]"),n='[data-snftt-version="'+t+'"]',o=document.querySelector(n),a=_createForOfIteratorHelperLoose$1(document.querySelectorAll("[data-snftt-version]"));!(e=a()).done;){var i=e.value;i.classList.remove("active","current"),i.setAttribute("aria-pressed","false")}null!=o&&(o.classList.add("active","current"),o.setAttribute("aria-pressed","true"),null!=r&&(r.textContent=o.dataset.snfttVersion))}function feedVersionsMenu(){var e=document.getElementById("versions-dropdown-menu");if(!e)return console.log("Did not find the versions dropdown menu."),!1;for(var t,r=_createForOfIteratorHelperLoose$1(docs_versions);!(t=r()).done;){var n=t.value,o=document.createElement("li"),a=document.createElement("a");a.classList.add("dropdown-item","d-flex","align-items-center","justify-content-between"),a.setAttribute("aria-pressed","false"),a.setAttribute("href",n.url),a.dataset.snfttVersionUrl=n.url,a.dataset.snfttVersion=n.name;var i=document.createElement("span");i.classList.add("small","ms-2"),i.textContent=n.name;var s=document.createElement("i");s.classList.add("bi","bi-check","ms-auto"),a.append(i),a.append(s),o.append(a),e.append(o)}return!0}function agentHas(e){return navigator.userAgent.toLowerCase().search(e.toLowerCase())>-1}function isFirefox(){return agentHas("Firefox")||agentHas("FxiOS")||agentHas("Focus")}function isSafari(){return(!!window.ApplePaySetupFeature||!!window.safari)&&agentHas("Safari")&&!agentHas("Chrome")&&!agentHas("CriOS")}function runWhenDOMContentLoaded(e){"loading"!=document.readyState?e():document.addEventListener?document.addEventListener("DOMContentLoaded",e):document.attachEvent("onreadystatechange",(function(){"complete"==document.readyState&&e()}))}function loadSphinxNefertiti(){if(fixFigureStyle(),-1==(new MenuHandler).init()&&(console.log("Could not find the