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"