Suitable versions of Sphinx for building different versions of CMake Docs?

Recently, I tried to configure and build the CMakeHelp project directly to generate CMake Docs locally. The following commands are my simple test of using Sphinx-6.2.1 to build the CMakeHelp of v3.18.6 tag:

sphinx-build --version
git clone --depth 1 --no-single-branch https://github.com/Kitware/CMake.git
cd CMake
git checkout v3.18.6 --quiet
git describe --tag
mkdir build && cd build
cmake ../Utilities/Sphinx -GNinja -DSPHINX_HTML=ON -DSPHINX_FLAGS="-A versionswitch=1"
cmake --build .

However, I found that the latest Sphinx version (currently, 6.2.1) cannot handle some previous versions of CMake Docs. The following error is generated by the above commands:

Extension error:
Could not import extension cmake (exception: No module named 'sphinx.util.pycompat')
ninja: build stopped: subcommand failed.
Click to expand the full logs
D:\Repo\tmp>sphinx-build --version
sphinx-build 6.2.1

D:\Repo\tmp>git clone --depth 1 --no-single-branch https://github.com/Kitware/CMake.git
Cloning into 'CMake'...
remote: Enumerating objects: 79159, done.
remote: Counting objects: 100% (79159/79159), done.
remote: Compressing objects: 100% (37657/37657), done.
remote: Total 79159 (delta 52343), reused 62038 (delta 38466), pack-reused 0
Receiving objects: 100% (79159/79159), 48.72 MiB | 4.45 MiB/s, done.
Resolving deltas: 100% (52343/52343), done.
Updating files: 100% (22981/22981), done.

D:\Repo\tmp>cd CMake

D:\Repo\tmp\CMake>git checkout v3.18.6 --quiet

D:\Repo\tmp\CMake>git describe --tag
v3.18.6

D:\Repo\tmp\CMake>mkdir build && cd build

D:\Repo\tmp\CMake\build>cmake ../Utilities/Sphinx -GNinja -DSPHINX_HTML=ON -DSPHINX_FLAGS="-A versionswitch=1"
-- Configuring done
-- Generating done
-- Build files have been written to: D:/Repo/tmp/CMake/build

D:\Repo\tmp\CMake\build>cmake --build .
[1/1] sphinx-build html: see Utilities/Sphinx/build-html.log
FAILED: doc_format_html D:/Repo/tmp/CMake/build/doc_format_html
cmd.exe /C "cd /D D:\Repo\tmp\CMake\build && C:\Python\Python310\Scripts\sphinx-build.exe -c D:/Repo/tmp/CMake/build -d D:/Repo/tmp/CMake/build/doctrees -b html -A versionswitch=1 D:/Repo/tmp/CMake/Help D:/Repo/tmp/CMake/build/html > build-html.log"

Extension error:
Could not import extension cmake (exception: No module named 'sphinx.util.pycompat')
ninja: build stopped: subcommand failed.

Even though I downgraded the Sphinx gradually, I still met some other different errors sometimes, which bothers me a lot.

Can CMake Team tell me which versions of Sphinx are suitable for building different versions of CMake Docs?

cc: @brad.king @craig.scott

For reference, CMake MR 8324 removed some compatibility code, so CMake 3.27’s docs will require Sphinx 2.x or higher.

If it still doesn’t build with the newest version of Sphinx, further merge requests are welcome to address that.

We do not maintain a mapping of CMake version to Sphinx version, but old CMake versions cannot be expected to support newer Sphinx versions that have removed compatibility with old Sphinx versions.

I noticed that there is an information about the version of Sphinx used to build the CMake Docs in the bottom of page. Maybe I can take it for reference:

image

cc: @brad.king

I found another problem when building the older version of CMake Docs:

  • Sphinx: 2.4.4
  • CMake Docs: v3.11.4

The followings are the commands I used to build the CMake Docs:

sphinx-build --version
git clone --depth 1 --no-single-branch https://github.com/Kitware/CMake.git
cd CMake
git checkout v3.11.4 --quiet
git describe --tag
mkdir build && cd build
cmake ../Utilities/Sphinx -GNinja -DSPHINX_HTML=ON -DSPHINX_FLAGS="-A versionswitch=1"
cmake --build .

Although there is no error showed up, there is an warning:

WARNING: while setting up extension sphinx.addnodes: node class 'meta' is already registered, its visitors will be overridden
Click to expand the full logs
D:\Repo\tmp>sphinx-build --version
sphinx-build 2.4.4

D:\Repo\tmp>git clone --depth 1 --no-single-branch https://github.com/Kitware/CMake.git
Cloning into 'CMake'...
remote: Enumerating objects: 79159, done.
remote: Counting objects: 100% (79159/79159), done.
remote: Compressing objects: 100% (37674/37674), done.
remote: Total 79159 (delta 52339), reused 62025 (delta 38449), pack-reused 0
Receiving objects: 100% (79159/79159), 48.72 MiB | 4.07 MiB/s, done.
Resolving deltas: 100% (52339/52339), done.
Updating files: 100% (22981/22981), done.

D:\Repo\tmp>cd CMake

D:\Repo\tmp\CMake>git checkout v3.11.4 --quiet

D:\Repo\tmp\CMake>git describe --tag
v3.11.4

D:\Repo\tmp\CMake>mkdir build && cd build

D:\Repo\tmp\CMake\build>cmake ../Utilities/Sphinx -GNinja -DSPHINX_HTML=ON -DSPHINX_FLAGS="-A versionswitch=1"
-- Configuring done
-- Generating done
-- Build files have been written to: D:/Repo/tmp/CMake/build

D:\Repo\tmp\CMake\build>cmake --build .
[1/1] sphinx-build html: see Utilities/Sphinx/build-html.log
WARNING: while setting up extension sphinx.addnodes: node class 'meta' is already registered, its visitors will be overridden

After opening the HTML files generated, I found that the gray background of “Content” disappears for some pages:

Comapred with the CMake Docs 3.11.4 hosted in the cmake.org:

I believe this phenomenon is related to the above-mentioned warning. What happened?

I think I found the solution to this warning:

WARNING: while setting up extension sphinx.addnodes: node class 'meta' is already registered, its visitors will be overridden

It seems that this warning is caused by the version of docutils, which has to be <0.18. After I downgrade the docutils from 0.18.1 to 0.17.1, the warning won’t show up again.

  • Sphinx: 2.4.4
  • Docutils: 0.17.1
  • CMake Docs: v3.11.4

The followings are my demo commands:

pip install docutils==0.17.1
sphinx-build --version
git clone --depth 1 --no-single-branch https://github.com/Kitware/CMake.git
cd CMake
git checkout v3.11.4 --quiet
git describe --tag
mkdir build && cd build
cmake ../Utilities/Sphinx -GNinja -DSPHINX_HTML=ON -DSPHINX_FLAGS="-A versionswitch=1"
cmake --build .
Click to expand the full logs
D:\Repo\tmp>pip install docutils==0.17.1
Collecting docutils==0.17.1
  Using cached docutils-0.17.1-py2.py3-none-any.whl (575 kB)
Installing collected packages: docutils
  Attempting uninstall: docutils
    Found existing installation: docutils 0.18.1
    Uninstalling docutils-0.18.1:
      Successfully uninstalled docutils-0.18.1
Successfully installed docutils-0.17.1

D:\Repo\tmp>sphinx-build --version
sphinx-build 2.4.4

D:\Repo\tmp>git clone --depth 1 --no-single-branch https://github.com/Kitware/CMake.git
Cloning into 'CMake'...
remote: Enumerating objects: 79159, done.
remote: Counting objects: 100% (79159/79159), done.
remote: Compressing objects: 100% (37660/37660), done.
remote: Total 79159 (delta 52339), reused 62041 (delta 38463), pack-reused 0
Receiving objects: 100% (79159/79159), 48.72 MiB | 3.63 MiB/s, done.
Resolving deltas: 100% (52339/52339), done.
Updating files: 100% (22981/22981), done.

D:\Repo\tmp>cd CMake

D:\Repo\tmp\CMake>git checkout v3.11.4 --quiet

D:\Repo\tmp\CMake>git describe --tag
v3.11.4

D:\Repo\tmp\CMake>mkdir build && cd build

D:\Repo\tmp\CMake\build>cmake ../Utilities/Sphinx -GNinja -DSPHINX_HTML=ON -DSPHINX_FLAGS="-A versionswitch=1"
-- Configuring done
-- Generating done
-- Build files have been written to: D:/Repo/tmp/CMake/build

D:\Repo\tmp\CMake\build>cmake --build .
[1/1] sphinx-build html: see Utilities/Sphinx/build-html.log

Reference:

As for the Extension Error that I mentioned at the beginning:

Extension error:
Could not import extension cmake (exception: No module named 'sphinx.util.pycompat')
ninja: build stopped: subcommand failed.

It seems that it’s because the pycompact module is deprecated at 4.0.0 and removed at 6.0.0.

Therefore, to remove this error, I just need to install the Sphinx with its version <6.0.0.

Testing with Sphinx-5.3.0 (Another extension error)

  • Sphinx: 5.3.0
  • CMake Docs: v3.18.6

If I install Sphinx with its versions >=4.0.0 and <6.0.0, there will be another extension error showed up:

Extension error:
Could not import extension cmake (exception: cannot import name 'htmlescape' from 'sphinx.util.pycompat' (C:\Python\Python310\lib\site-packages\sphinx\util\pycompat.py))
Click to expand the full logs
D:\Repo\tmp>sphinx-build --version
sphinx-build 5.3.0

D:\Repo\tmp>git clone --depth 1 --no-single-branch https://github.com/Kitware/CMake.git
Cloning into 'CMake'...
remote: Enumerating objects: 79159, done.
remote: Counting objects: 100% (79159/79159), done.
remote: Compressing objects: 100% (37660/37660), done.
remote: Total 79159 (delta 52339), reused 62041 (delta 38463), pack-reused 0
Receiving objects: 100% (79159/79159), 48.72 MiB | 3.41 MiB/s, done.
Resolving deltas: 100% (52339/52339), done.
Updating files: 100% (22981/22981), done.

D:\Repo\tmp>cd CMake

D:\Repo\tmp\CMake>git checkout v3.18.6 --quiet

D:\Repo\tmp\CMake>git describe --tag
v3.18.6

D:\Repo\tmp\CMake>mkdir build && cd build

D:\Repo\tmp\CMake\build>cmake ../Utilities/Sphinx -GNinja -DSPHINX_HTML=ON -DSPHINX_FLAGS="-A versionswitch=1"
-- Configuring done
-- Generating done
-- Build files have been written to: D:/Repo/tmp/CMake/build

D:\Repo\tmp\CMake\build>cmake --build .
[1/1] sphinx-build html: see Utilities/Sphinx/build-html.log
FAILED: doc_format_html D:/Repo/tmp/CMake/build/doc_format_html
cmd.exe /C "cd /D D:\Repo\tmp\CMake\build && C:\Python\Python310\Scripts\sphinx-build.exe -c D:/Repo/tmp/CMake/build -d D:/Repo/tmp/CMake/build/doctrees -b html -A versionswitch=1 D:/Repo/tmp/CMake/Help D:/Repo/tmp/CMake/build/html > build-html.log"

Extension error:
Could not import extension cmake (exception: cannot import name 'htmlescape' from 'sphinx.util.pycompat' (C:\Python\Python310\lib\site-packages\sphinx\util\pycompat.py))
ninja: build stopped: subcommand failed.

Testing with Sphinx-3.5.4 (ImportError)

  • Sphinx: 3.5.4
  • CMake Docs: v3.18.6

If I install Sphinx with its versions >=3.0.0 and <4.0.0 , there will be an ImportError showed up:

ImportError: cannot import name 'Union' from 'types' (C:\Python\Python310\lib\types.py)
Click to expand the full logs
D:\Repo\tmp>sphinx-build --version
Traceback (most recent call last):
  File "C:\Python\Python310\lib\runpy.py", line 196, in _run_module_as_main
    return _run_code(code, main_globals, None,
  File "C:\Python\Python310\lib\runpy.py", line 86, in _run_code
    exec(code, run_globals)
  File "C:\Python\Python310\Scripts\sphinx-build.exe\__main__.py", line 4, in <module>
  File "C:\Python\Python310\lib\site-packages\sphinx\cmd\build.py", line 25, in <module>
    from sphinx.application import Sphinx
  File "C:\Python\Python310\lib\site-packages\sphinx\application.py", line 32, in <module>
    from sphinx.config import Config
  File "C:\Python\Python310\lib\site-packages\sphinx\config.py", line 23, in <module>
    from sphinx.util import logging
  File "C:\Python\Python310\lib\site-packages\sphinx\util\__init__.py", line 35, in <module>
    from sphinx.util import smartypants  # noqa
  File "C:\Python\Python310\lib\site-packages\sphinx\util\smartypants.py", line 33, in <module>
    from sphinx.util.docutils import __version_info__ as docutils_version
  File "C:\Python\Python310\lib\site-packages\sphinx\util\docutils.py", line 31, in <module>
    from sphinx.util.typing import RoleFunction
  File "C:\Python\Python310\lib\site-packages\sphinx\util\typing.py", line 34, in <module>
    from types import Union as types_Union
ImportError: cannot import name 'Union' from 'types' (C:\Python\Python310\lib\types.py)

Testing with Sphinx-2.4.5 (No error or warning)

  • Sphinx: 2.4.5
  • CMake Docs: v3.18.6

If I install Sphinx with its versions <3.0.0, there will be no error or warning showed up:

Click to expand the full logs
D:\Repo\tmp>sphinx-build --version
sphinx-build 2.4.5

D:\Repo\tmp>git clone --depth 1 --no-single-branch https://github.com/Kitware/CMake.git
Cloning into 'CMake'...
remote: Enumerating objects: 79159, done.
remote: Counting objects: 100% (79159/79159), done.
remote: Compressing objects: 100% (37660/37660), done.
remote: Total 79159 (delta 52339), reused 62041 (delta 38463), pack-reused 0
Receiving objects: 100% (79159/79159), 48.72 MiB | 4.72 MiB/s, done.
Resolving deltas: 100% (52339/52339), done.
Updating files: 100% (22981/22981), done.

D:\Repo\tmp>cd CMake

D:\Repo\tmp\CMake>git checkout v3.18.6 --quiet

D:\Repo\tmp\CMake>git describe --tag
v3.18.6

D:\Repo\tmp\CMake>mkdir build && cd build

D:\Repo\tmp\CMake\build>cmake ../Utilities/Sphinx -GNinja -DSPHINX_HTML=ON -DSPHINX_FLAGS="-A versionswitch=1"
-- Configuring done
-- Generating done
-- Build files have been written to: D:/Repo/tmp/CMake/build

D:\Repo\tmp\CMake\build>cmake --build .
[1/1] sphinx-build html: see Utilities/Sphinx/build-html.log

Reference:

cc: @brad.king

Recently, I met a problem when I use sphinx <= 2.4.5 to build the documentation of cmake <= 3.8. That is, there are lots of warning messages showed up after completing the build, for example:

WARNING: 4 column based index found. It might be a bug of extensions you use: [('pair', 'variable ; GRAPHVIZ_GRAPH_TYPE', 'variable:GRAPHVIZ_GRAPH_TYPE', 'main')]
WARNING: 4 column based index found. It might be a bug of extensions you use: [('pair', 'variable ; GRAPHVIZ_GRAPH_NAME', 'variable:GRAPHVIZ_GRAPH_NAME', 'main')]
WARNING: 4 column based index found. It might be a bug of extensions you use: [('pair', 'variable ; GRAPHVIZ_GRAPH_HEADER', 'variable:GRAPHVIZ_GRAPH_HEADER', 'main')]

and the strange background color of the generated HTML files:

The followings are the commands I use:

pip install sphinx==2.4.5 docutils==0.17.1 jinja2==3.0.0
sphinx-build --version
git clone --depth 1 --no-single-branch https://github.com/Kitware/CMake.git
cd CMake
git checkout v3.5.2 --quiet
git describe --tag
mkdir build && cd build
cmake ../Utilities/Sphinx -DSPHINX_HTML=ON -DSPHINX_FLAGS="-A versionswitch=1"
cmake --build .

And the following is the log of the above commands:

log.txt (72.6 KB)

Do you know what happened? I guess it might be related to Sphinx’s dependencies. And the followings are the requirements when I install sphinx==2.4.5:

Requirement already satisfied: sphinx==2.4.5 in c:\python\python310\lib\site-packages (2.4.5)
Requirement already satisfied: docutils==0.17.1 in c:\python\python310\lib\site-packages (0.17.1)
Requirement already satisfied: jinja2==3.0.0 in c:\python\python310\lib\site-packages (3.0.0)
Requirement already satisfied: sphinxcontrib-applehelp in c:\python\python310\lib\site-packages (from sphinx==2.4.5) (1.0.2)
Requirement already satisfied: sphinxcontrib-devhelp in c:\python\python310\lib\site-packages (from sphinx==2.4.5) (1.0.2)
Requirement already satisfied: sphinxcontrib-jsmath in c:\python\python310\lib\site-packages (from sphinx==2.4.5) (1.0.1)
Requirement already satisfied: sphinxcontrib-htmlhelp in c:\python\python310\lib\site-packages (from sphinx==2.4.5) (2.0.0)
Requirement already satisfied: sphinxcontrib-serializinghtml in c:\python\python310\lib\site-packages (from sphinx==2.4.5) (1.1.5)
Requirement already satisfied: sphinxcontrib-qthelp in c:\python\python310\lib\site-packages (from sphinx==2.4.5) (1.0.3)
Requirement already satisfied: Pygments>=2.0 in c:\users\hwhsu1231\appdata\roaming\python\python310\site-packages (from sphinx==2.4.5) (2.14.0)
Requirement already satisfied: snowballstemmer>=1.1 in c:\python\python310\lib\site-packages (from sphinx==2.4.5) (2.2.0)
Requirement already satisfied: babel!=2.0,>=1.3 in c:\python\python310\lib\site-packages (from sphinx==2.4.5) (2.11.0)
Requirement already satisfied: alabaster<0.8,>=0.7 in c:\python\python310\lib\site-packages (from sphinx==2.4.5) (0.7.12)
Requirement already satisfied: imagesize in c:\python\python310\lib\site-packages (from sphinx==2.4.5) (1.4.1)
Requirement already satisfied: requests>=2.5.0 in c:\python\python310\lib\site-packages (from sphinx==2.4.5) (2.28.1)
Requirement already satisfied: setuptools in c:\python\python310\lib\site-packages (from sphinx==2.4.5) (59.8.0)
Requirement already satisfied: packaging in c:\users\hwhsu1231\appdata\roaming\python\python310\site-packages (from sphinx==2.4.5) (23.0)
Requirement already satisfied: colorama>=0.3.5 in c:\users\hwhsu1231\appdata\roaming\python\python310\site-packages (from sphinx==2.4.5) (0.4.6)
Requirement already satisfied: MarkupSafe>=2.0.0rc2 in c:\python\python310\lib\site-packages (from jinja2==3.0.0) (2.1.1)
Requirement already satisfied: pytz>=2015.7 in c:\python\python310\lib\site-packages (from babel!=2.0,>=1.3->sphinx==2.4.5) (2022.6)
Requirement already satisfied: charset-normalizer<3,>=2 in c:\python\python310\lib\site-packages (from requests>=2.5.0->sphinx==2.4.5) (2.1.1)
Requirement already satisfied: idna<4,>=2.5 in c:\users\hwhsu1231\appdata\roaming\python\python310\site-packages (from requests>=2.5.0->sphinx==2.4.5) (2.8)
Requirement already satisfied: urllib3<1.27,>=1.21.1 in c:\python\python310\lib\site-packages (from requests>=2.5.0->sphinx==2.4.5) (1.26.12)
Requirement already satisfied: certifi>=2017.4.17 in c:\python\python310\lib\site-packages (from requests>=2.5.0->sphinx==2.4.5) (2022.9.14)

Hello, CMake Team. There’s something I want to confirm. Is it:

  1. technically impossible, or
  2. technically possible but just lack of motivation

to maintain those old CMake versions (ex. 3.0, 3.1, 3.2,…etc) to upgrade their Sphinx version to the latest?

For example, if CMake upgrades its Sphinx version to v7.2.6 in master version, then all of the previous released versions, 3.0~3.28(the current latest release), will upgrade their Sphinx as well. Is it technically possible to do so?

I suspect other changes may need backported to those source trees. But CMake generates its docs from the source tree, so some tracking of how to update these releases to newer Sphinx would best be tracked in the history as well (basically, branch off of the last 3.0.x release, update it to work with new Sphinx, then regenerate and merge the changes into master with -s ours for tracking purposes). What would be the benefit of regenerating the docs?

Hello, @ben.boeckel

Over the past months, I’ve been working on making the localization project for CMake Documentation (using Sphinx’s Internationalization), in which I also designed the mechanism to translate all the possible versions listed in the version switcher: v3.0~v3.xx, latest, and git-master. The following screenshot is the demo result:

In short, my localization project will store the generated Gettext .po files, so that CMake can use these .po files to build its documentation in mulitple languages. (Just like Python Documentation)

However, there are some restrictions when building different versions of CMake Documentation:

  • For v3.0~v3.8, we should use sphinx-1.6.1
  • For v3.9~v3.18, we should use sphinx-2.4.5
  • For v3.19~v3.27, we should use sphinx-5.3.0
  • For v3.28~, we can use sphinx-6.3.0

Besides, based on this topic, it seems that the version switcher must be added manually to the generated html documentation before v3.9.0.

Therefore, I hope that CMake Team can fix those older versions, and they had better being able to use the same version of Sphinx as the latest version uses.

Maybe something for its own dedicated thread, but do you only intend to translate past releases, or also the current release? There are often documentation updates for the current release, and I’m wondering how you plan to ensure all translations pick up those doc updates. It won’t be feasible to expect any contributors or the CMake maintainers to notify you or anyone else when such doc updates are made, so you’d need some way to detect or be notified of this yourself.

I also expect there to be some challenges during the release candidate phase of a new release, unless you don’t intend to do any translations until after the release candidate stage (i.e. only for formal .0 releases or later).

Hello, @craig.scott

Don’t worry about this. I’ve writen a series of GitHub Workflows to help me update each version.

  • For git-master version, if there exist new commits, it will update and create a PR.
  • For v3.x or latest version, if there exist new tags, it will update and create a PR.
  • …etc.

When I was designing this project, I took into consideration that even if I were the only one maintaining it, I could do so without any stress.

I’ve also considered the release candidate as well. The following is what I wrote for detecting the latest tag of each release version. You can take a look.

Click to expand
function(get_git_latest_tag_on_tag_pattern)
    #
    # Parse arguments.
    #
    set(TAG_OPTIONS)
    set(TAG_ONE_VALUE_ARGS      IN_REPO_PATH 
                                IN_TAG_PATTERN 
                                OUT_TAG)
    set(TAG_MULTI_VALUE_ARGS)
    cmake_parse_arguments(ARGS 
        "${TAG_OPTIONS}"
        "${TAG_ONE_VALUE_ARGS}"
        "${TAG_MULTI_VALUE_ARGS}"
        ${ARGN})
    #
    # Ensure all required arguments are provided.
    #
    set(REQUIRED_ARGS           IN_REPO_PATH 
                                IN_TAG_PATTERN 
                                OUT_TAG)
    foreach(ARG ${REQUIRED_ARGS})
        if(NOT DEFINED ARGS_${ARG})
            message(FATAL_ERROR "Missing ARGS_${ARG} argument.")
        endif()
    endforeach()
    if(NOT EXISTS "${Git_EXECUTABLE}")
        find_package(Git QUIET MODULE REQUIRED)
    endif()
    #
    # Get a list of tags matching the tag pattern.
    #
    execute_process(
        COMMAND "${Git_EXECUTABLE}" tag --list
            --sort=-v:refname
            "${ARGS_IN_TAG_PATTERN}"
        WORKING_DIRECTORY "${PROJ_OUT_REPO_DIR}"
        RESULT_VARIABLE RES_VAR
        OUTPUT_VARIABLE OUT_VAR
        ERROR_VARIABLE  ERR_VAR
        OUTPUT_STRIP_TRAILING_WHITESPACE
        ERROR_STRIP_TRAILING_WHITESPACE)
    string(REPLACE "\n" ";" TAG_LIST "${OUT_VAR}")
    #
    # Get a list of release candidate tags matching the tag pattern.
    #
    execute_process(
        COMMAND "${Git_EXECUTABLE}" tag --list
            --sort=-v:refname
            "${ARGS_IN_TAG_PATTERN}-rc*"
        WORKING_DIRECTORY "${PROJ_OUT_REPO_DIR}"
        RESULT_VARIABLE RES_VAR
        OUTPUT_VARIABLE OUT_VAR
        ERROR_VARIABLE  ERR_VAR
        OUTPUT_STRIP_TRAILING_WHITESPACE
        ERROR_STRIP_TRAILING_WHITESPACE)
    string(REPLACE "\n" ";" TAG_RC_LIST "${OUT_VAR}")
    #
    # Get a list of release tags matching the tag pattern.
    #
    set(TAG_REL_LIST "${TAG_LIST}")
    list(REMOVE_ITEM TAG_REL_LIST ${TAG_RC_LIST})
    #
    # Get the max release candidate tag.
    #
    if(TAG_RC_LIST)
        list(GET TAG_RC_LIST 0 TAG_RC_MAX)
    else()
        set(TAG_RC_MAX)
    endif()
    #
    # Get the max release tag.
    #
    if(TAG_REL_LIST)
        list(GET TAG_REL_LIST 0 TAG_REL_MAX)
    else()
        set(TAG_REL_MAX)
    endif()
    #
    # If there exists ${TAG_REL_MAX}, consider release version.
    # Otherwise, consider release candidate version.
    #
    if(NOT TAG_REL_MAX STREQUAL "")
        set(LATEST_TAG ${TAG_REL_MAX})
    else()
        if(NOT TAG_RC_MAX STREQUAL "")
            set(LATEST_TAG ${TAG_RC_MAX})
        else()
            message(FATAL_ERROR "There is no available tag on ${ARGS_IN_TAG_PATTERN}")
        endif()
    endif()
    #
    # Return the latest tag on ${ARGS_IN_TAG_PATTERN}.
    #
    set(${ARGS_OUT_TAG} "${LATEST_TAG}" PARENT_SCOPE)
endfunction()

Hello, CMake Team.

From the research of this topic, it appears that the issue is actually a bug from Sphinx itself. Therefore, it can be resolved by fixing the issue in a new version of Sphinx. However, some old versions of CMake files can only be built using old versions of Sphinx, so they won’t be able to fix this issue. This is why I hope the CMake team will continue to maintain the Sphinx documentation system for older versions of CMake.

Additionally, I hope that the CMake project, like other projects using Sphinx, would prepare a requirements.txt file specifying the required Sphinx version and other dependencies. This way, users only need to run pip install -r requirements.txt before building the documentation, without worrying about which version of Sphinx to install. For instance, to build documentation for all versions of CMake, I had to prepare corresponding requirements.txt files in the project as shown below:

If CMake project can prepare a requirements.txt, then this code can be removed. All I need to do is to find the requirements.txt and run pip install -r to install it.

Hello, CMake Team.

About what @ben.boeckel mentioned previously:

Here is the full log and the screenshot from vscode-git-graph of my experimental demo:

Click to expand the full log
hwhsu1231@vb-kubuntu:~/Repo/testing/test-git-merge-s-ours$ git status
On branch master
nothing to commit, working tree clean
hwhsu1231@vb-kubuntu:~/Repo/testing/test-git-merge-s-ours$ git log --oneline
249f752 (HEAD -> master) Init the repo
hwhsu1231@vb-kubuntu:~/Repo/testing/test-git-merge-s-ours$ echo "v3.0.0" >> v3.0.0.txt
hwhsu1231@vb-kubuntu:~/Repo/testing/test-git-merge-s-ours$ git add .
hwhsu1231@vb-kubuntu:~/Repo/testing/test-git-merge-s-ours$ git commit -m "Add v3.0.0 for release-3.0"
[master 4435866] Add v3.0.0 for release-3.0
 1 file changed, 1 insertion(+)
 create mode 100644 v3.0.0.txt
hwhsu1231@vb-kubuntu:~/Repo/testing/test-git-merge-s-ours$ git tag v3.0.0
hwhsu1231@vb-kubuntu:~/Repo/testing/test-git-merge-s-ours$ echo "v3.1.0" >> v3.1.0.txt
hwhsu1231@vb-kubuntu:~/Repo/testing/test-git-merge-s-ours$ git add .
hwhsu1231@vb-kubuntu:~/Repo/testing/test-git-merge-s-ours$ git commit -m "Add v3.1.0 for release-3.1"
[master 4e629da] Add v3.1.0 for release-3.1
 1 file changed, 1 insertion(+)
 create mode 100644 v3.1.0.txt
hwhsu1231@vb-kubuntu:~/Repo/testing/test-git-merge-s-ours$ git tag v3.1.0
hwhsu1231@vb-kubuntu:~/Repo/testing/test-git-merge-s-ours$ echo "v3.2.0" >> v3.2.0.txt
hwhsu1231@vb-kubuntu:~/Repo/testing/test-git-merge-s-ours$ git add .
hwhsu1231@vb-kubuntu:~/Repo/testing/test-git-merge-s-ours$ git commit -m "Add v3.2.0 for release-3.2"
[master 75df260] Add v3.2.0 for release-3.2
 1 file changed, 1 insertion(+)
 create mode 100644 v3.2.0.txt
hwhsu1231@vb-kubuntu:~/Repo/testing/test-git-merge-s-ours$ git tag v3.2.0
hwhsu1231@vb-kubuntu:~/Repo/testing/test-git-merge-s-ours$ git checkout v3.0.0
Note: switching to 'v3.0.0'.

You are in 'detached HEAD' state. You can look around, make experimental
changes and commit them, and you can discard any commits you make in this
state without impacting any branches by switching back to a branch.

If you want to create a new branch to retain commits you create, you may
do so (now or later) by using -c with the switch command. Example:

  git switch -c <new-branch-name>

Or undo this operation with:

  git switch -

Turn off this advice by setting config variable advice.detachedHead to false

HEAD is now at 4435866 Add v3.0.0 for release-3.0
hwhsu1231@vb-kubuntu:~/Repo/testing/test-git-merge-s-ours$ git branch release-3.0
hwhsu1231@vb-kubuntu:~/Repo/testing/test-git-merge-s-ours$ git checkout release-3.0
Switched to branch 'release-3.0'
hwhsu1231@vb-kubuntu:~/Repo/testing/test-git-merge-s-ours$ echo "v3.0.1" >> v3.0.1.txt
hwhsu1231@vb-kubuntu:~/Repo/testing/test-git-merge-s-ours$ git add .
hwhsu1231@vb-kubuntu:~/Repo/testing/test-git-merge-s-ours$ git commit -m "Add v3.0.1 for release-3.0"
[release-3.0 da4df98] Add v3.0.1 for release-3.0
 1 file changed, 1 insertion(+)
 create mode 100644 v3.0.1.txt
hwhsu1231@vb-kubuntu:~/Repo/testing/test-git-merge-s-ours$ git tag v3.0.1
hwhsu1231@vb-kubuntu:~/Repo/testing/test-git-merge-s-ours$ git checkout master
Switched to branch 'master'
hwhsu1231@vb-kubuntu:~/Repo/testing/test-git-merge-s-ours$ git merge --strategy=ours release-3.0
Merge made by the 'ours' strategy.
hwhsu1231@vb-kubuntu:~/Repo/testing/test-git-merge-s-ours$ git log --oneline --graph
*   263d93d (HEAD -> master) Merge branch 'release-3.0'
|\  
| * da4df98 (tag: v3.0.1, release-3.0) Add v3.0.1 for release-3.0
* | 75df260 (tag: v3.2.0) Add v3.2.0 for release-3.2
* | 4e629da (tag: v3.1.0) Add v3.1.0 for release-3.1
|/  
* 4435866 (tag: v3.0.0) Add v3.0.0 for release-3.0
* 249f752 Init the repo
hwhsu1231@vb-kubuntu:~/Repo/testing/test-git-merge-s-ours$ 

Is the operation he described exactly like this? If so, does CMake Team use this method to handle all the patches for those older releases?

The topology looks fine to me at a first glance (hard to tell if the merge is -s ours or not).