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

diff --git a/.github/workflows/doc.yml b/.github/workflows/doc.yml
index 292df4cfee10abb342680673b565ad62c8d2d220..75f467cde7cbf4fa3ae0ea1f5d08a07c44218d92 100644 (file)
--- 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 cebb6644c2a91f46052cc7ae0e632356d6d2b4b3..5542d98504ede988f3159f074bac42de15a825de 100644 (file)
--- 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
index dc414cfdebe16dae375e268cb40f0c39b9ccd1ac..d8d2a8f3cd2d15a5f01f6cccb103f06d5a781cbf 100644 (file)
--- 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 2bc914b3cd7735231f931cdc61b94bee8d64a6ae..28baafa38ea71dce4a113040a39e50ebe9ca2bc7 100644 (file)
--- 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 de79bafe194450383d5b1f35fe667dca7c809a7e..73eb38cf45d7bf7e22a56b157c6936cabd278173 100644 (file)
--- 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 543202bf4b075c9be8f371b4304e9dc110386715..14158ae814a7c2ae5a189cf4e6fb0f7d9d22bd97 100644 (file)
--- 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 ca56d866cec1c437e3b5262067b49958e4a33912..8e74dc302e35321bdca9a005766b8553318b8e6a 100644 (file)
--- 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 5987fa7627f981e8035774e1a6659d007c431b36..11aafb818f59c9ecf52158a69da34c3813776c77 100644 (file)
--- 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):