fix: place the las_update value in the meta of each page (#1409)

* fix: place the las_update value in the meta of each page * docs: add documentation on build date * docs: typo in ref * Update docs/user_guide/layout.rst Co-authored-by: Daniel McCloy <dan@mccloy.info> * Update docs/user_guide/layout.rst Co-authored-by: Daniel McCloy <dan@mccloy.info> * docs: refactor build date documentation * docs rewording * go back to upstream sphinx-sitemap --------- Co-authored-by: Daniel McCloy <dan@mccloy.info>
pydata · Aug 21, 2023 · 78d60a3 · 78d60a3
1 parent ae7af87
commit 78d60a3
Show file tree

Hide file tree

Showing 4 changed files with 27 additions and 1 deletion.
diff --git a/docs/conf.py b/docs/conf.py
@@ -92,6 +92,7 @@
 html_logo = "_static/logo.svg"
 html_favicon = "_static/logo.svg"
 html_sourcelink_suffix = ""
+html_last_updated_fmt = ""  # to reveal the build date in the pages meta
 
 # Define the json_url for our version switcher.
 json_url = "https://pydata-sphinx-theme.readthedocs.io/en/latest/_static/switcher.json"

diff --git a/docs/user_guide/layout.rst b/docs/user_guide/layout.rst
@@ -567,3 +567,25 @@ could do so with the following steps:
       "navbar_start": ["navbar-logo", "version"],
       # ...
       }
+
+Build date
+==========
+
+By default this theme does not display the build date even when Sphinx's `html_last_updated_fmt <https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_last_updated_fmt>`__ variable is set. If you want the build date displayed, the theme includes a :code:`last-updated` template that you can add to one of the page regions in your ``conf.py``. For example:
+
+.. code-block:: python
+    :caption: conf.py
+
+    html_theme_options = {
+        "content_footer_items": ["last-updated"],
+        # other settings...
+    }
+
+If you do specify ``html_last_updated_fmt`` but don't include the :code:`last-updated` template, the theme will still write the build date into a ``meta`` tag in the HTML header, which can be inspected by viewing the page source or extracted with an HTML parser. The tag will look like:
+
+.. code-block:: html
+
+    <meta name="docbuild:last-update" content="Aug 15, 2023">
+
+The tag's ``content`` attribute will follow the format specified in the ``html_last_updated_fmt`` configuration variable.
+
diff --git a/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html b/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html
@@ -39,6 +39,9 @@
 {%- block extrahead %}
   <meta name="viewport" content="width=device-width, initial-scale=1"/>
   <meta name="docsearch:language" content="{{ language }}"/>
+  {%- if last_updated %}
+    <meta name="docbuild:last-update" content="{{ last_updated | e }}"/>
+  {%- endif %}
 {%- endblock extrahead %}
 {% block body_tag %}
   {# set up with scrollspy to update the toc as we scroll #}

diff --git a/tools/github_actions_install.sh b/tools/github_actions_install.sh
@@ -10,7 +10,7 @@ elif [[ "$SPHINX_VERSION" == "dev" ]]; then
     SPHINX_INSTALL="git+https://github.com/sphinx-doc/sphinx"
     if [[ "$1" == "doc" ]]; then
         # Until they release a new version that undoes the max sphinx pin...
-        DEP_EXTRA="git+https://github.com/executablebooks/MyST-NB git+https://github.com/larsoner/sphinx-sitemap.git@path"
+        DEP_EXTRA="git+https://github.com/executablebooks/MyST-NB"
     fi
 elif [[ "$SPHINX_VERSION" == "old" ]]; then
     SPHINX_INSTALL="sphinx==5.0"