From 92ea56a3b5dee6fe4dd0109d52b7ab1b39a19c89 Mon Sep 17 00:00:00 2001
From: Rambaud Pierrick <12rambau@users.noreply.github.com>
Date: Tue, 15 Aug 2023 17:28:39 +0000
Subject: [PATCH 1/8] fix: place the las_update value in the meta of each page
---
docs/conf.py | 1 +
src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html | 3 +++
2 files changed, 4 insertions(+)
diff --git a/docs/conf.py b/docs/conf.py
index c0e32ccb4..986b4ba4e 100644
--- 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/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html b/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html
index b387ae3f2..a3c33ab92 100644
--- 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 %}
+ {%- if last_updated %}
+
+ {%- endif %}
{%- endblock extrahead %}
{% block body_tag %}
{# set up with scrollspy to update the toc as we scroll #}
From e424443890df01bb17ae59d0ac023f88683aacab Mon Sep 17 00:00:00 2001
From: Rambaud Pierrick <12rambau@users.noreply.github.com>
Date: Tue, 15 Aug 2023 19:55:32 +0000
Subject: [PATCH 2/8] docs: add documentation on build date
---
docs/user_guide/extending.rst | 31 +++++++++++++++++++++++++++++++
docs/user_guide/layout.rst | 15 +++++++++++++++
2 files changed, 46 insertions(+)
diff --git a/docs/user_guide/extending.rst b/docs/user_guide/extending.rst
index 050679bee..6fb91cad4 100644
--- a/docs/user_guide/extending.rst
+++ b/docs/user_guide/extending.rst
@@ -246,3 +246,34 @@ And add the following css to your custom.css file:
:end-before: /* end-custom-youtube
:code: css
:class: highlight-css
+
+.. _extending-build-date:
+
+Build date
+==========
+
+No component is available by default to display the build date in this theme. If you need one please consider the following snippets as a starting point to build your custom component.
+
+First go to the ``_templates`` directory of your documentation folder and create a ``last-updated.html`` file:
+
+.. code-block:: html
+
+
+
+ {%- if last_updated %}
+ {% trans last_updated=last_updated|e %}Last updated on {{ last_updated }}.{% endtrans %}
+ {%- endif %}
+
+
+Then add this template to any section of the documentation using your ``conf.py`` e.g. the footer:
+
+.. code-block:: python
+
+ # docs/conf.py
+
+ templates_path = ["_templates"] # don't forget to add the templates folder
+ html_last_updated_fmt = "" # select any format you see fit
+ html_theme_options = {
+ # [...]
+ "footer_start": ["last-updated"], # work as well with the extension
+ }
diff --git a/docs/user_guide/layout.rst b/docs/user_guide/layout.rst
index 018f32679..f08cb970e 100644
--- a/docs/user_guide/layout.rst
+++ b/docs/user_guide/layout.rst
@@ -567,3 +567,18 @@ could do so with the following steps:
"navbar_start": ["navbar-logo", "version"],
# ...
}
+
+Build date
+==========
+
+By design the build date cannot be seen in our template even when the `html_last_updated_fmt `__ is set. Instead the theme is adding a ``meta`` tag in the html head that can be read by html parser.
+
+.. code-block:: html
+
+
+
+The content will be respecting the format specified in the ``html_last_updated_fmt`` conf variable.
+
+.. note::
+
+ If a special component to display such an information in your page is your need please see :ref:`_extending-build-date`.
From d55ad4fdc83359a78e8f56b71f92bf4ca82dbc8f Mon Sep 17 00:00:00 2001
From: Rambaud Pierrick <12rambau@users.noreply.github.com>
Date: Tue, 15 Aug 2023 20:29:47 +0000
Subject: [PATCH 3/8] docs: typo in ref
---
docs/user_guide/layout.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/user_guide/layout.rst b/docs/user_guide/layout.rst
index f08cb970e..7e0929c81 100644
--- a/docs/user_guide/layout.rst
+++ b/docs/user_guide/layout.rst
@@ -581,4 +581,4 @@ The content will be respecting the format specified in the ``html_last_updated_f
.. note::
- If a special component to display such an information in your page is your need please see :ref:`_extending-build-date`.
+ If a special component to display such an information in your page is your need please see :ref:`extending-build-date`.
From dd66dc130c1928ae4fcb37cda5b4cbbbb171cfe8 Mon Sep 17 00:00:00 2001
From: Rambaud Pierrick <12rambau@users.noreply.github.com>
Date: Sat, 19 Aug 2023 11:45:00 +0200
Subject: [PATCH 4/8] Update docs/user_guide/layout.rst
Co-authored-by: Daniel McCloy
---
docs/user_guide/layout.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/user_guide/layout.rst b/docs/user_guide/layout.rst
index 7e0929c81..148104b89 100644
--- a/docs/user_guide/layout.rst
+++ b/docs/user_guide/layout.rst
@@ -577,7 +577,7 @@ By design the build date cannot be seen in our template even when the `html_last
-The content will be respecting the format specified in the ``html_last_updated_fmt`` conf variable.
+The tag's ``content`` attribute will follow the format specified in the ``html_last_updated_fmt`` configuration variable.
.. note::
From 1606c255e9a31d076f50a481504af32075100fbd Mon Sep 17 00:00:00 2001
From: Rambaud Pierrick <12rambau@users.noreply.github.com>
Date: Sat, 19 Aug 2023 11:46:35 +0200
Subject: [PATCH 5/8] Update docs/user_guide/layout.rst
Co-authored-by: Daniel McCloy
---
docs/user_guide/layout.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/user_guide/layout.rst b/docs/user_guide/layout.rst
index 148104b89..3c1aff9ab 100644
--- a/docs/user_guide/layout.rst
+++ b/docs/user_guide/layout.rst
@@ -571,7 +571,7 @@ could do so with the following steps:
Build date
==========
-By design the build date cannot be seen in our template even when the `html_last_updated_fmt `__ is set. Instead the theme is adding a ``meta`` tag in the html head that can be read by html parser.
+By design the build date cannot be seen in our template even when the `html_last_updated_fmt `__ is set. Instead the theme adds a ``meta`` tag in the HTML head that specifies the build date, which can be inspected by viewing the page source or extracted with an HTML parser. The tag will look like:
.. code-block:: html
From 9008acb0b12b957c088f197deaa7e5a14cbc6efb Mon Sep 17 00:00:00 2001
From: Rambaud Pierrick <12rambau@users.noreply.github.com>
Date: Sat, 19 Aug 2023 09:52:34 +0000
Subject: [PATCH 6/8] docs: refactor build date documentation
---
docs/user_guide/extending.rst | 31 -------------------------------
docs/user_guide/layout.rst | 4 ++--
2 files changed, 2 insertions(+), 33 deletions(-)
diff --git a/docs/user_guide/extending.rst b/docs/user_guide/extending.rst
index 6fb91cad4..050679bee 100644
--- a/docs/user_guide/extending.rst
+++ b/docs/user_guide/extending.rst
@@ -246,34 +246,3 @@ And add the following css to your custom.css file:
:end-before: /* end-custom-youtube
:code: css
:class: highlight-css
-
-.. _extending-build-date:
-
-Build date
-==========
-
-No component is available by default to display the build date in this theme. If you need one please consider the following snippets as a starting point to build your custom component.
-
-First go to the ``_templates`` directory of your documentation folder and create a ``last-updated.html`` file:
-
-.. code-block:: html
-
-
-
- {%- if last_updated %}
- {% trans last_updated=last_updated|e %}Last updated on {{ last_updated }}.{% endtrans %}
- {%- endif %}
-
-
-Then add this template to any section of the documentation using your ``conf.py`` e.g. the footer:
-
-.. code-block:: python
-
- # docs/conf.py
-
- templates_path = ["_templates"] # don't forget to add the templates folder
- html_last_updated_fmt = "" # select any format you see fit
- html_theme_options = {
- # [...]
- "footer_start": ["last-updated"], # work as well with the extension
- }
diff --git a/docs/user_guide/layout.rst b/docs/user_guide/layout.rst
index 3c1aff9ab..30b473a24 100644
--- a/docs/user_guide/layout.rst
+++ b/docs/user_guide/layout.rst
@@ -571,7 +571,7 @@ could do so with the following steps:
Build date
==========
-By design the build date cannot be seen in our template even when the `html_last_updated_fmt `__ is set. Instead the theme adds a ``meta`` tag in the HTML head that specifies the build date, which can be inspected by viewing the page source or extracted with an HTML parser. The tag will look like:
+By default the build date cannot be seen in our template even when the `html_last_updated_fmt `__ is set. Instead the theme adds a ``meta`` tag in the HTML head that specifies the build date, which can be inspected by viewing the page source or extracted with an HTML parser. The tag will look like:
.. code-block:: html
@@ -581,4 +581,4 @@ The tag's ``content`` attribute will follow the format specified in the ``html_l
.. note::
- If a special component to display such an information in your page is your need please see :ref:`extending-build-date`.
+ If a special component to display such an information in your page is your need please use the built-in :code:`last-updated`.
From dcf80af9b8c921b11efe8e0d3f8b59116c89551f Mon Sep 17 00:00:00 2001
From: Daniel McCloy
Date: Mon, 21 Aug 2023 09:57:42 -0500
Subject: [PATCH 7/8] docs rewording
---
docs/user_guide/layout.rst | 15 +++++++++++----
1 file changed, 11 insertions(+), 4 deletions(-)
diff --git a/docs/user_guide/layout.rst b/docs/user_guide/layout.rst
index 30b473a24..ee822eb40 100644
--- a/docs/user_guide/layout.rst
+++ b/docs/user_guide/layout.rst
@@ -571,7 +571,17 @@ could do so with the following steps:
Build date
==========
-By default the build date cannot be seen in our template even when the `html_last_updated_fmt `__ is set. Instead the theme adds a ``meta`` tag in the HTML head that specifies the build date, which can be inspected by viewing the page source or extracted with an HTML parser. The tag will look like:
+By default this theme does not display the build date even when Sphinx's `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
@@ -579,6 +589,3 @@ By default the build date cannot be seen in our template even when the `html_las
The tag's ``content`` attribute will follow the format specified in the ``html_last_updated_fmt`` configuration variable.
-.. note::
-
- If a special component to display such an information in your page is your need please use the built-in :code:`last-updated`.
From 37243998dc7d69684a510209de0e255a5dae9d88 Mon Sep 17 00:00:00 2001
From: Daniel McCloy
Date: Mon, 21 Aug 2023 09:59:57 -0500
Subject: [PATCH 8/8] go back to upstream sphinx-sitemap
---
tools/github_actions_install.sh | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/tools/github_actions_install.sh b/tools/github_actions_install.sh
index 15e3b1a47..521e87b7f 100755
--- 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"