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
krb5 · May 27, 2021 · 3fa40a3 · 3fa40a3
1 parent bbce6a8
commit 3fa40a3
Show file tree

Hide file tree

Showing 8 changed files with 27 additions and 8 deletions.
diff --git 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
@@ -55,7 +55,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
@@ -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
@@ -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
@@ -1,4 +1,4 @@
-.. highlightlang:: c
+.. highlight:: c
 
 .. _krb5-ui4-struct:
 

diff --git a/doc/conf.py b/doc/conf.py
@@ -98,8 +98,15 @@
 
 # -- 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
@@ -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
@@ -1,4 +1,4 @@
-.. highlightlang:: c
+.. highlight:: c
 
 .. $composite.struct_reference($composite.name):