Add documentation for HPKE

Author: Legrandin

.readthedocs.yaml

@@ -1,7 +1,7 @@
 version: 2
 python:
   install:
-    - requirements: Doc/requirements.txt
+    - requirements: Doc/requirements-docs.txt
 build:
   os: ubuntu-22.04
   tools:

Doc/Makefile

@@ -14,7 +14,7 @@ ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 # the i18n builder cannot share the environment and doctrees with the others
 I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 
-.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
+.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp latex latexpdf text man changes linkcheck doctest gettext
 
 help:
 	@echo "Please use \`make <target>' where <target> is one of"
@@ -26,7 +26,6 @@ help:
 	@echo "  htmlhelp   to make HTML files and a HTML help project"
 	@echo "  qthelp     to make HTML files and a qthelp project"
 	@echo "  devhelp    to make HTML files and a Devhelp project"
-	@echo "  epub       to make an epub"
 	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
 	@echo "  latexpdf   to make LaTeX files and run them through pdflatex"
 	@echo "  text       to make text files"
@@ -90,11 +89,6 @@ devhelp:
 	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/PyCryptodome"
 	@echo "# devhelp"
 
-epub:
-	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
-	@echo
-	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
-
 latex:
 	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
 	@echo

Doc/conf.py

@@ -54,13 +54,13 @@ def have_aes_ni(self):
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = [ 'sphinx.ext.autodoc', 'sphinx.ext.napoleon',
-        'sphinx.ext.mathjax' ]
+        'sphinx.ext.mathjax', 'sphinx_autodoc_typehints' ]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
 # The suffix of source filenames.
-source_suffix = '.rst'
+source_suffix = {'.rst': 'restructuredtext'}
 
 # The encoding of source files.
 #source_encoding = 'utf-8-sig'
@@ -70,7 +70,7 @@ def have_aes_ni(self):
 
 # General information about the project.
 project = 'PyCryptodome'
-copyright = '2022, Helder Eijs'
+copyright = '2025, Helder Eijs'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the

Doc/reqs.txt

@@ -0,0 +1,2 @@
+sphinx==8.2.3
+sphinx-autodoc-typehints==3.1.0

Doc/requirements-docs.txt

@@ -4,6 +4,7 @@
 From https://github.com/ryan-roemer/sphinx-bootstrap-theme.
 """
 
+import os
 from os import path
 from sys import version_info as python_version
 
@@ -12,14 +13,18 @@
 from sphinx.util.logging import getLogger
 
 
-__version__ = '1.1.2alpha1'
+__version__ = '3.0.2'
 __version_full__ = __version__
 
 logger = getLogger(__name__)
 
 
 def get_html_theme_path():
     """Return list of HTML theme paths."""
+    logger.warning(
+        _('Calling get_html_theme_path is deprecated. If you are calling it to define html_theme_path, you are safe to remove that code.')
+    )
+
     cur_dir = path.abspath(path.dirname(path.dirname(__file__)))
     return cur_dir
 
@@ -31,40 +36,69 @@ def config_initiated(app, config):
             _('The canonical_url option is deprecated, use the html_baseurl option from Sphinx instead.')
         )
 
+    if theme_options.get("analytics_id"):
+        logger.warning(
+            _('The analytics_id option is deprecated, use the sphinxcontrib-googleanalytics extension instead.')
+        )
+
+    if theme_options.get("analytics_anonymize_ip"):
+        logger.warning(
+            _('The analytics_anonymize_ip option is deprecated, use the sphinxcontrib-googleanalytics extension instead.')
+        )
+
+    if "extra_css_files" in config.html_context:
+        logger.warning(
+            _('The extra_css_file option is deprecated, use the html_css_files option from Sphinx instead.')
+        )
+
 
 def extend_html_context(app, pagename, templatename, context, doctree):
      # Add ``sphinx_version_info`` tuple for use in Jinja templates
      context['sphinx_version_info'] = sphinx_version
 
+     # Inject all the Read the Docs environment variables in the context:
+     # https://docs.readthedocs.io/en/stable/reference/environment-variables.html
+     context['READTHEDOCS'] = os.environ.get("READTHEDOCS", False) == "True"
+     if context['READTHEDOCS']:
+         for key, value in os.environ.items():
+             if key.startswith("READTHEDOCS_"):
+                 context[key] = value
+
+
 
 # See http://www.sphinx-doc.org/en/stable/theming.html#distribute-your-theme-as-a-python-package
 def setup(app):
     if python_version[0] < 3:
-        logger.warning("Python 2 is deprecated with sphinx_rtd_theme, update to Python 3")
-    app.require_sphinx('1.6')
-    if sphinx_version <= (2, 0, 0):
-        logger.warning("Sphinx 1.x is deprecated with sphinx_rtd_theme, update to Sphinx 2.x or greater")
-        if not app.config.html_experimental_html5_writer:
-            logger.warning("'html4_writer' is deprecated with sphinx_rtd_theme")
-    else:
-        if app.config.html4_writer:
-            logger.warning("'html4_writer' is deprecated with sphinx_rtd_theme")
+        logger.error("Python 2 is not supported with sphinx_rtd_theme, update to Python 3.")
+
+    app.require_sphinx('6.0')
+    if app.config.html4_writer:
+        logger.error("'html4_writer' is not supported with sphinx_rtd_theme.")
+
+    # Since Sphinx 6, jquery isn't bundled anymore and we need to ensure that
+    # the sphinxcontrib-jquery extension is enabled.
+    # See: https://dev.readthedocs.io/en/latest/design/sphinx-jquery.html
+    if sphinx_version >= (6, 0, 0):
+        # Documentation of Sphinx guarantees that an extension is added and
+        # enabled at most once.
+        # See: https://www.sphinx-doc.org/en/master/extdev/appapi.html#sphinx.application.Sphinx.setup_extension
+        app.setup_extension("sphinxcontrib.jquery")
+        # However, we need to call the extension's callback since setup_extension doesn't do it
+        # See: https://github.com/sphinx-contrib/jquery/issues/23
+        from sphinxcontrib.jquery import add_js_files as jquery_add_js_files
+        jquery_add_js_files(app, app.config)
 
     # Register the theme that can be referenced without adding a theme path
     app.add_html_theme('sphinx_rtd_theme', path.abspath(path.dirname(__file__)))
 
-    if sphinx_version >= (1, 8, 0):
-        # Add Sphinx message catalog for newer versions of Sphinx
-        # See http://www.sphinx-doc.org/en/master/extdev/appapi.html#sphinx.application.Sphinx.add_message_catalog
-        rtd_locale_path = path.join(path.abspath(path.dirname(__file__)), 'locale')
-        app.add_message_catalog('sphinx', rtd_locale_path)
-        app.connect('config-inited', config_initiated)
+    # Add Sphinx message catalog for newer versions of Sphinx
+    # See http://www.sphinx-doc.org/en/master/extdev/appapi.html#sphinx.application.Sphinx.add_message_catalog
+    rtd_locale_path = path.join(path.abspath(path.dirname(__file__)), 'locale')
+    app.add_message_catalog('sphinx', rtd_locale_path)
+    app.connect('config-inited', config_initiated)
 
     # sphinx emits the permalink icon for headers, so choose one more in keeping with our theme
-    if sphinx_version >= (3, 5, 0):
-        app.config.html_permalinks_icon = "\uf0c1"
-    else:
-        app.config.html_add_permalinks = "\uf0c1"
+    app.config.html_permalinks_icon = "\uf0c1"
 
     # Extend the default context when rendering the templates.
     app.connect("html-page-context", extend_html_context)

Doc/requirements.txt

@@ -7,47 +7,47 @@
   {%- set titlesuffix = "" %}
 {%- endif %}
 {%- set lang_attr = 'en' if language == None else (language | replace('_', '-')) %}
-{%- set sphinx_writer = 'writer-html5' if html5_doctype else 'writer-html4' -%}
 
 {# Build sphinx_version_info tuple from sphinx_version string in pure Jinja #}
 {%- set (_ver_major, _ver_minor) = (sphinx_version.split('.') | list)[:2] | map('int') -%}
 {%- set sphinx_version_info = (_ver_major, _ver_minor, -1) -%}
 
 <!DOCTYPE html>
-<html class="{{ sphinx_writer }}" lang="{{ lang_attr }}" >
+<html class="writer-html5" lang="{{ lang_attr }}"{% if sphinx_version_info >= (7, 2) %} data-content_root="{{ content_root }}"{% endif %}>
 <head>
   <meta charset="utf-8" />
+  {%- if READTHEDOCS and not embedded %}
+  <meta name="readthedocs-addons-api-version" content="1">
+  {%- endif %}
   {{- metatags }}
   <meta name="viewport" content="width=device-width, initial-scale=1.0" />
   {%- block htmltitle %}
   <title>{{ title|striptags|e }}{{ titlesuffix }}</title>
   {%- endblock -%}
 
   {#- CSS #}
-  {%- if sphinx_version_info < (4, 0) -%}
-    <link rel="stylesheet" href="{{ pathto('_static/' + style, 1) }}" type="text/css" />
-    <link rel="stylesheet" href="{{ pathto('_static/pygments.css', 1) }}" type="text/css" />
-  {%- endif %}
-  {%- for css in css_files %}
-    {%- if css|attr("rel") %}
-      <link rel="{{ css.rel }}" href="{{ pathto(css.filename, 1) }}" type="text/css"{% if css.title is not none %} title="{{ css.title }}"{% endif %} />
+  {%- for css_file in css_files %}
+    {%- if css_file|attr("filename") %}
+      {{ css_tag(css_file) }}
     {%- else %}
-      <link rel="stylesheet" href="{{ pathto(css, 1) }}" type="text/css" />
+      <link rel="stylesheet" href="{{ pathto(css_file, 1)|escape }}" type="text/css" />
     {%- endif %}
   {%- endfor %}
 
-  {%- for cssfile in extra_css_files %}
-    <link rel="stylesheet" href="{{ pathto(cssfile, 1) }}" type="text/css" />
+  {#
+      "extra_css_files" is an undocumented Read the Docs theme specific option.
+      There is no need to check for ``|attr("filename")`` here because it's always a string.
+      Note that this option should be removed in favor of regular ``html_css_files``:
+      https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_css_files
+  #}
+  {%- for css_file in extra_css_files %}
+    <link rel="stylesheet" href="{{ pathto(css_file, 1)|escape }}" type="text/css" />
   {%- endfor -%}
 
   {#- FAVICON #}
-  {%- if favicon %}
-    {%- if sphinx_version_info < (4, 0) -%}
-    <link rel="shortcut icon" href="{{ pathto('_static/' + favicon, 1) }}"/>
-    {%- else %}
+  {%- if favicon_url %}
     <link rel="shortcut icon" href="{{ favicon_url }}"/>
-    {%- endif %}
-  {%- endif -%}
+  {%- endif %}
 
   {#- CANONICAL URL (deprecated) #}
   {%- if theme_canonical_url and not pageurl %}
@@ -61,36 +61,16 @@
 
   {#- JAVASCRIPTS #}
   {%- block scripts %}
-  <!--[if lt IE 9]>
-    <script src="{{ pathto('_static/js/html5shiv.min.js', 1) }}"></script>
-  <![endif]-->
   {%- if not embedded %}
-  {# XXX Sphinx 1.8.0 made this an external js-file, quick fix until we refactor the template to inherert more blocks directly from sphinx #}
-    {%- if sphinx_version_info >= (1, 8) -%}
-      {%- if sphinx_version_info < (4, 0) -%}
-      <script id="documentation_options" data-url_root="{{ url_root }}" src="{{ pathto('_static/documentation_options.js', 1) }}"></script>
-      {%- endif -%}
-      {%- for scriptfile in script_files %}
-        {{ js_tag(scriptfile) }}
-      {%- endfor %}
-    {%- else %}
-      <script>
-          var DOCUMENTATION_OPTIONS = {
-              URL_ROOT:'{{ url_root }}',
-              VERSION:'{{ release|e }}',
-              LANGUAGE:'{{ language }}',
-              COLLAPSE_INDEX:false,
-              FILE_SUFFIX:'{{ '' if no_search_suffix else file_suffix }}',
-              HAS_SOURCE:  {{ has_source|lower }},
-              SOURCELINK_SUFFIX: '{{ sourcelink_suffix }}'
-          };
-      </script>
-      {%- for scriptfile in script_files %}
-        <script src="{{ pathto(scriptfile, 1) }}"></script>
-      {%- endfor %}
-    {%- endif %}
+    {%- for scriptfile in script_files %}
+      {{ js_tag(scriptfile) }}
+    {%- endfor %}
     <script src="{{ pathto('_static/js/theme.js', 1) }}"></script>
 
+    {%- if READTHEDOCS or DEBUG %}
+    <script src="{{ pathto('_static/js/versions.js', 1) }}"></script>
+    {%- endif %}
+
     {#- OPENSEARCH #}
     {%- if use_opensearch %}
     <link rel="search" type="application/opensearchdescription+xml"
@@ -133,32 +113,22 @@
         <div class="wy-side-nav-search" {% if theme_style_nav_header_background %} style="background: {{theme_style_nav_header_background}}" {% endif %}>
           {%- block sidebartitle %}
 
-          {%- if logo and theme_logo_only %}
-            <a href="{{ pathto(master_doc) }}">
-          {%- else %}
-            <a href="{{ pathto(master_doc) }}" class="icon icon-home"> {{ project }}
-          {%- endif %}
-
-          {%- if logo %}
-            {#- Not strictly valid HTML, but it's the only way to display/scale
-                it properly, without weird scripting or heaps of work
-            #}
-            {%- if sphinx_version_info < (4, 0) -%}
-            <img src="{{ pathto('_static/' + logo, 1) }}" class="logo" alt="{{ _('Logo') }}"/>
-            {%- else %}
-            <img src="{{ logo_url }}" class="logo" alt="{{ _('Logo') }}"/>
+          {# the logo helper function was removed in Sphinx 6 and deprecated since Sphinx 4 #}
+          {# the master_doc variable was renamed to root_doc in Sphinx 4 (master_doc still exists in later Sphinx versions) #}
+          {%- set _logo_url = logo_url|default(pathto('_static/' + (logo or ""), 1)) %}
+          {%- set _root_doc = root_doc|default(master_doc) %}
+          <a href="{{ pathto(_root_doc) }}"{% if not theme_logo_only %} class="icon icon-home"{% endif %}>
+            {% if not theme_logo_only %}{{ project }}{% endif %}
+            {%- if logo or logo_url %}
+              <img src="{{ _logo_url }}" class="logo" alt="{{ _('Logo') }}"/>
             {%- endif %}
-          {%- endif %}
           </a>
 
-          {%- if theme_display_version %}
-            {%- set nav_version = version %}
-            {%- if READTHEDOCS and current_version %}
-              {%- set nav_version = current_version %}
-            {%- endif %}
-            {%- if nav_version %}
-              <div class="version">
-                {{ nav_version }}
+          {%- if READTHEDOCS or DEBUG %}
+            {%- if theme_version_selector or theme_language_selector %}
+              <div class="switch-menus">
+                <div class="version-switch"></div>
+                <div class="language-switch"></div>
               </div>
             {%- endif %}
           {%- endif %}