docs/sphinx/layout/layout.html

<!--
Copyright 2024 The Pigweed Authors

Licensed under the Apache License, Version 2.0 (the "License"); you may not
use this file except in compliance with the License. You may obtain a copy of
the License at

    https://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations under
the License.
-->

{% extends "pydata_sphinx_theme/layout.html" %}

{# htmltitle controls the HTML title node. On some pages we customize
   the title to make it more usable. #}
{% block htmltitle %}
  {# Override the title for some module pages. #}
  {% if pagename.startswith('pw_') %}
    {% set tokens = pagename.split('/') %}
    {% set module_name = tokens[0] %}
    {% set maybe_doc_name = tokens[1] %}
    {% if maybe_doc_name == 'docs' %}
      {# It's the homepage for a module. Use the normal title. #}
      <title>{{ title|striptags|e }}{{ titlesuffix }}</title>
    {% else %}
      {# It's a subpage of the module's docs, e.g. the API reference.
         Prepend the module's name so that it's easier to see what module
         this doc is related to. E.g. before our change the default title
         just says "API reference - Pigweed" and after our change it says
         "pw_string: API reference - Pigweed". #}
      <title>{{ module_name }}: {{ title|striptags|e }}{{ titlesuffix }}</title>
    {% endif %}
  {# It's a non-module page. Use the normal title. #}
  {% else %}
    <title>{{ title|striptags|e }}{{ titlesuffix }}</title>
  {% endif %}
{% endblock %}

{% block header %}
  <!-- `pw-sentinel` will be replaced during site build
       post-processing (`docs/common/__init__.py`) with the
       compiled universal site header. -->
  <!-- pw-sentinel -->
{% endblock header %}

{#
   Override extrahead to prevent loading of the client-side Sphinx
   search scripts that we no longer need.
   https://github.com/pydata/pydata-sphinx-theme/blob/v0.18.0/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html#L33
#}
{% block extrahead %}
  <meta name="viewport" content="width=device-width, initial-scale=1"/>
{% endblock extrahead %}

{% block docs_main %}
  {{ super() }}
  {# The following scripts are loaded after the main content in order to
     improve load performance. Background:
     https://developer.chrome.com/docs/lighthouse/performance/render-blocking-resources #}
  {# Always load pigweed.js after Sphinx's scripts because pigweed.js
     relies on classes and data from Sphinx's scripts. #}
  <script src="{{ pathto('_static/js/pigweed.js', 1) | e }}"></script>
{% endblock docs_main %}