From 0bf023bdbb8335f48a6a4dcf8bd5dac9c2cd7fb6 Mon Sep 17 00:00:00 2001
From: Greg Hudson <ghudson@mit.edu>
Date: Wed, 26 May 2021 15:08:28 -0400
Subject: [PATCH] Fix doc build for Sphinx 4.0
Use app.add_css_file() to register krb5.css if possible (it was added
in Sphinx 1.8), since the old name app.add_stylesheet() was removed in
Sphinx 4.0.
Use the highlight directive instead of the highlightlang directive,
which was removed in Sphinx 4.0.
Remove two duplicate table of contents entries to fix warnings.
In the Github Actions configuration, add a second doc build using the
newest version of Sphinx.
ticket: 9006
tags: pullup
target_version: 1.19-next
(cherry picked from commit 3fa40a32e22cb9de91fa1d18deddcba446515855)
---
.github/workflows/doc.yml | 16 +++++++++++++++-
doc/appdev/refs/macros/index.rst | 1 -
doc/appdev/refs/types/index.rst | 1 -
doc/appdev/refs/types/krb5_int32.rst | 2 +-
doc/appdev/refs/types/krb5_ui_4.rst | 2 +-
doc/conf.py | 9 ++++++++-
doc/tools/define_document.tmpl | 2 +-
doc/tools/type_document.tmpl | 2 +-
8 files changed, 27 insertions(+), 8 deletions(-)
diff --git a/.github/workflows/doc.yml b/.github/workflows/doc.yml
index 292df4cfe..75f467cde 100644
--- a/.github/workflows/doc.yml
+++ b/.github/workflows/doc.yml
@@ -5,7 +5,7 @@ on:
pull_request: {paths: [doc/**, src/doc/*, src/include/krb5/krb5.hin, .github/workflows/doc.yml]}
jobs:
- doc:
+ doc-older-sphinx:
runs-on: ubuntu-18.04
steps:
- name: Checkout repository
@@ -19,6 +19,20 @@ jobs:
run: |
cd src/doc
make -f Makefile.in SPHINX_ARGS=-W htmlsrc
+ doc-newest-sphinx:
+ runs-on: ubuntu-18.04
+ steps:
+ - name: Checkout repository
+ uses: actions/checkout@v1
+ - name: Linux setup
+ run: |
+ sudo apt-get update -qq
+ sudo apt-get install -y doxygen python3-lxml python3-pip
+ pip3 install Cheetah3 sphinx
+ - name: Build documentation
+ run: |
+ cd src/doc
+ make -f Makefile.in SPHINX_ARGS=-W htmlsrc
- name: Upload HTML
uses: actions/upload-artifact@v2
with:
diff --git a/doc/appdev/refs/macros/index.rst b/doc/appdev/refs/macros/index.rst
index 4d51e795c..0cb2e81bd 100644
--- a/doc/appdev/refs/macros/index.rst
+++ b/doc/appdev/refs/macros/index.rst
@@ -54,7 +54,6 @@ Public
ENCTYPE_DES3_CBC_RAW.rst
ENCTYPE_DES3_CBC_SHA.rst
ENCTYPE_DES3_CBC_SHA1.rst
- ENCTYPE_DES3_CBC_SHA1.rst
ENCTYPE_DES_CBC_CRC.rst
ENCTYPE_DES_CBC_MD4.rst
ENCTYPE_DES_CBC_MD5.rst
diff --git a/doc/appdev/refs/types/index.rst b/doc/appdev/refs/types/index.rst
index dc414cfde..d8d2a8f3c 100644
--- a/doc/appdev/refs/types/index.rst
+++ b/doc/appdev/refs/types/index.rst
@@ -62,7 +62,6 @@ Public
krb5_preauthtype.rst
krb5_principal.rst
krb5_principal_data.rst
- krb5_const_principal.rst
krb5_prompt.rst
krb5_prompt_type.rst
krb5_prompter_fct.rst
diff --git a/doc/appdev/refs/types/krb5_int32.rst b/doc/appdev/refs/types/krb5_int32.rst
index 2bc914b3c..28baafa38 100644
--- a/doc/appdev/refs/types/krb5_int32.rst
+++ b/doc/appdev/refs/types/krb5_int32.rst
@@ -1,4 +1,4 @@
-.. highlightlang:: c
+.. highlight:: c
.. _krb5-int32-struct:
diff --git a/doc/appdev/refs/types/krb5_ui_4.rst b/doc/appdev/refs/types/krb5_ui_4.rst
index de79bafe1..73eb38cf4 100644
--- a/doc/appdev/refs/types/krb5_ui_4.rst
+++ b/doc/appdev/refs/types/krb5_ui_4.rst
@@ -1,4 +1,4 @@
-.. highlightlang:: c
+.. highlight:: c
.. _krb5-ui4-struct:
diff --git a/doc/conf.py b/doc/conf.py
index 4fb6aae14..a876fd633 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -98,8 +98,15 @@ pygments_style = 'sphinx'
# -- Options for HTML output ---------------------------------------------------
+# When we can rely on Sphinx 1.8 (released Sep 2018) we can just set:
+# html_css_files = ['kerb.css']
+# But in the meantime, we add this file using either a way that works
+# after 1.8 or a way that works before 4.0.
def setup(app):
- app.add_stylesheet('kerb.css')
+ if callable(getattr(app, 'add_css_file', None)):
+ app.add_css_file('kerb.css')
+ else:
+ app.add_stylesheet('kerb.css')
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
diff --git a/doc/tools/define_document.tmpl b/doc/tools/define_document.tmpl
index ca56d866c..8e74dc302 100644
--- a/doc/tools/define_document.tmpl
+++ b/doc/tools/define_document.tmpl
@@ -1,4 +1,4 @@
-.. highlightlang:: c
+.. highlight:: c
.. $composite.macro_reference($composite.name):
diff --git a/doc/tools/type_document.tmpl b/doc/tools/type_document.tmpl
index 5987fa762..11aafb818 100644
--- a/doc/tools/type_document.tmpl
+++ b/doc/tools/type_document.tmpl
@@ -1,4 +1,4 @@
-.. highlightlang:: c
+.. highlight:: c
.. $composite.struct_reference($composite.name):