tag referring to it. The value of this option must be the
> > \# base URL from which the finished HTML is served.
> > \#html\_use\_opensearch = ''
> >
> > \# This is the file name suffix for HTML files (e.g. ".xhtml").
> > \#html\_file\_suffix = None
> >
> > \# Language to be used for generating the HTML full-text search index.
> > \# Sphinx supports the following languages:
> > \# 'da', 'de', 'en', 'es', 'fi', 'fr', 'h', 'it', 'ja'
> > \# 'nl', 'no', 'pt', 'ro', 'r', 'sv', 'tr'
> > \#html\_search\_language = 'en'
> >
> > \# A dictionary with options for the search language support, empty by default.
> > \# Now only 'ja' uses this config value
> > \#html\_search\_options = {'type': 'default'}
> >
> > \# The name of a javascript file (relative to the configuration directory) that
> > \# implements a search results scorer. If empty, the default will be used.
> > \#html\_search\_scorer = 'scorer.js'
> >
> > \# Output file base name for HTML help builder.
> > htmlhelp\_basename = 'TheLinuxKerneldoc'
> >
> > \# -- Options for LaTeX output ---------------------------------------------
> >
> > latex\_elements = {
> > # The paper size ('letterpaper' or 'a4paper').
> > 'papersize': 'a4paper',
> >
> > # The font size ('10pt', '11pt' or '12pt').
> > 'pointsize': '11pt',
> >
> > # Latex figure (float) alignment
> > #'figure\_align': 'htbp',
> >
> > # Don't mangle with UTF-8 chars
> > 'inputenc': '',
> > 'utf8extra': '',
> >
> > # Set document margins
> > 'sphinxsetup': '''
> > hmargin=0.5in, vmargin=1in,
> > parsedliteralwraps=true,
> > verbatimhintsturnover=false,
> > ''',
> >
> > # For CJK One-half spacing, need to be in front of hyperref
> > 'extrapackages': r'\\usepackage{setspace}',
> >
> > # Additional stuff for the LaTeX preamble.
> > 'preamble': '''
> > % Use some font with UTF-8 support with XeLaTeX
> > \\\\usepackage{fontspec}
> > \\\\setsansfont{DejaVu Sans}
> > \\\\setromanfont{DejaVu Serif}
> > \\\\setmonofont{DejaVu Sans Mono}
> > ''',
> > }
> >
> > \# Fix reference escape troubles with Sphinx 1.4.x
> > if major == 1:
> > latex\_elements\['preamble'\] += '\\\\renewcommand\*{\\\\DUrole}\[2\]{ #2 }\\n'
> >
> >
> > \# Load kerneldoc specific LaTeX settings
> > latex\_elements\['preamble'\] += '''
> > % Load kerneldoc specific LaTeX settings
> > \\\\input{kerneldoc-preamble.sty}
> > '''
> >
> > \# With Sphinx 1.6, it is possible to change the Bg color directly
> > \# by using:
> > \# \\definecolor{sphinxnoteBgColor}{RGB}{204,255,255}
> > \# \\definecolor{sphinxwarningBgColor}{RGB}{255,204,204}
> > \# \\definecolor{sphinxattentionBgColor}{RGB}{255,255,204}
> > \# \\definecolor{sphinximportantBgColor}{RGB}{192,255,204}
> > \#
> > \# However, it require to use sphinx heavy box with:
> > \#
> > \# \\renewenvironment{sphinxlightbox} {%
> > \# \\\\begin{sphinxheavybox}
> > \# }
> > \# \\\\end{sphinxheavybox}
> > \# }
> > \#
> > \# Unfortunately, the implementation is buggy: if a note is inside a
> > \# table, it isn't displayed well. So, for now, let's use boring
> > \# black and white notes.
> >
> > \# Grouping the document tree into LaTeX files. List of tuples
> > \# (source start file, target name, title,
> > \# author, documentclass \[howto, manual, or own class\]).
> > \# Sorted in alphabetical order
> > latex\_documents = \[
> > \]
> >
> > \# Add all other index files from Documentation/ subdirectories
> > for fn in os.listdir('.'):
> > doc = os.path.join(fn, "index")
> > if os.path.exists(doc + ".rst"):
> > has = False
> > for l in latex\_documents:
> > if l\[0\] == doc:
> > has = True
> > break
> > if not has:
> > latex\_documents.append((doc, fn + '.tex',
> > 'Linux %s Documentation' % fn.capitalize(),
> > 'The kernel development community',
> > 'manual'))
> >
> > \# The name of an image file (relative to this directory) to place at the top of
> > \# the title page.
> > \#latex\_logo = None
> >
> > \# For "manual" documents, if this is true, then toplevel headings are parts,
> > \# not chapters.
> > \#latex\_use\_parts = False
> >
> > \# If true, show page references after internal links.
> > \#latex\_show\_pagerefs = False
> >
> > \# If true, show URL addresses after external links.
> > \#latex\_show\_urls = False
> >
> > \# Documents to append as an appendix to all manuals.
> > \#latex\_appendices = \[\]
> >
> > \# If false, no module index is generated.
> > \#latex\_domain\_indices = True
> >
> > \# Additional LaTeX stuff to be copied to build directory
> > latex\_additional\_files = \[
> > 'sphinx/kerneldoc-preamble.sty',
> > \]
> >
> >
> > \# -- Options for manual page output ---------------------------------------
> >
> > \# One entry per manual page. List of tuples
> > \# (source start file, name, description, authors, manual section).
> > man\_pages = \[
> > (master\_doc, 'thelinuxkernel', 'The Linux Kernel Documentation',
> > \[author\], 1)
> > \]
> >
> > \# If true, show URL addresses after external links.
> > \#man\_show\_urls = False
> >
> >
> > \# -- Options for Texinfo output -------------------------------------------
> >
> > \# Grouping the document tree into Texinfo files. List of tuples
> > \# (source start file, target name, title, author,
> > \# dir menu entry, description, category)
> > texinfo\_documents = \[
> > (master\_doc, 'TheLinuxKernel', 'The Linux Kernel Documentation',
> > author, 'TheLinuxKernel', 'One line description of project.',
> > 'Miscellaneous'),
> > \]
> >
> > \# Documents to append as an appendix to all manuals.
> > \#texinfo\_appendices = \[\]
> >
> > \# If false, no module index is generated.
> > \#texinfo\_domain\_indices = True
> >
> > \# How to display URL addresses: 'footnote', 'no', or 'inline'.
> > \#texinfo\_show\_urls = 'footnote'
> >
> > \# If true, do not generate a @detailmenu in the "Top" node's menu.
> > \#texinfo\_no\_detailmenu = False
> >
> >
> > \# -- Options for Epub output ----------------------------------------------
> >
> > \# Bibliographic Dublin Core info.
> > epub\_title = project
> > epub\_author = author
> > epub\_publisher = author
> > epub\_copyright = copyright
> >
> > \# The basename for the epub file. It defaults to the project name.
> > \#epub\_basename = project
> >
> > \# The HTML theme for the epub output. Since the default themes are not
> > \# optimized for small screen space, using the same theme for HTML and epub
> > \# output is usually not wise. This defaults to 'epub', a theme designed to save
> > \# visual space.
> > \#epub\_theme = 'epub'
> >
> > \# The language of the text. It defaults to the language option
> > \# or 'en' if the language is not set.
> > \#epub\_language = ''
> >
> > \# The scheme of the identifier. Typical schemes are ISBN or URL.
> > \#epub\_scheme = ''
> >
> > \# The unique identifier of the text. This can be a ISBN number
> > \# or the project homepage.
> > \#epub\_identifier = ''
> >
> > \# A unique identification for the text.
> > \#epub\_uid = ''
> >
> > \# A tuple containing the cover image and cover page html template filenames.
> > \#epub\_cover = ()
> >
> > \# A sequence of (type, uri, title) tuples for the guide element of content.opf.
> > \#epub\_guide = ()
> >
> > \# HTML files that should be inserted before the pages created by sphinx.
> > \# The format is a list of tuples containing the path and title.
> > \#epub\_pre\_files = \[\]
> >
> > \# HTML files that should be inserted after the pages created by sphinx.
> > \# The format is a list of tuples containing the path and title.
> > \#epub\_post\_files = \[\]
> >
> > \# A list of files that should not be packed into the epub file.
> > epub\_exclude\_files = \['search.html'\]
> >
> > \# The depth of the table of contents in toc.ncx.
> > \#epub\_tocdepth = 3
> >
> > \# Allow duplicate toc entries.
> > \#epub\_tocdup = True
> >
> > \# Choose between 'default' and 'includehidden'.
> > \#epub\_tocscope = 'default'
> >
> > \# Fix unsupported image types using the Pillow.
> > \#epub\_fix\_images = False
> >
> > \# Scale large images.
> > \#epub\_max\_image\_width = 0
> >
> > \# How to display URL addresses: 'footnote', 'no', or 'inline'.
> > \#epub\_show\_urls = 'inline'
> >
> > \# If false, no index is generated.
> > \#epub\_use\_index = True
> >
> > \#=======
> > \# rst2pdf
> > \#
> > \# Grouping the document tree into PDF files. List of tuples
> > \# (source start file, target name, title, author, options).
> > \#
> > \# See the Sphinx chapter of https://ralsina.me/static/manual.pdf
> > \#
> > \# FIXME: Do not add the index file here; the result will be too big. Adding
> > \# multiple PDF files here actually tries to get the cross-referencing right
> > \# \*between\* PDF files.
> > pdf\_documents = \[
> > ('kernel-documentation', u'Kernel', u'Kernel', u'J. Random Bozo'),
> > \]
> >
> > \# kernel-doc extension configuration for running Sphinx directly (e.g. by Read
> > \# the Docs). In a normal build, these are supplied from the Makefile via command
> > \# line arguments.
> > kerneldoc\_bin = '../scripts/kernel-doc'
> > kerneldoc\_srctree = '..'
> >
> > \# ------------------------------------------------------------------------------
> > \# Since loadConfig overwrites settings from the global namespace, it has to be
> > \# the last statement in the conf.py file
> > \# ------------------------------------------------------------------------------
> > loadConfig(globals())\`
> >
> > \### Environment Information
> >
> > \`\`\`text
> > sphinx-build --bug-report
> > Please paste all output below into the bug report template
> >
> >
> >
> > Platform: linux; (Linux-6.2.0-rc3-x86\_64-with-glibc2.36)
> > Python version: 3.11.1 (main, Dec 31 2022, 10:23:59) \[GCC 12.2.0\])
> > Python implementation: CPython
> > Sphinx version: 6.1.3
> > Docutils version: 0.19
> > Jinja2 version: 3.0.3
> > Pygments version: 2.14.0
> > \`\`\`
> >
> >
> > \### Sphinx extensions
> >
> > \_No response\_
> >
> > \### Additional context
> >
> > \_No response\_
> > \`\`\`
---
### Author:  [@hwhsu1231](https://discourse.cmake.org/u/hwhsu1231)
#### Post date: [June 19, 2023, 12:17pm UTC](https://discourse.cmake.org/t/suitable-versions-of-sphinx-for-building-different-versions-of-cmake-docs/7982/7 "2023-06-19T12:17:58Z")
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:
```auto
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:
```auto
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](https://discourse.cmake.org/uploads/short-url/pZDVrdy48AIVgeI7fwPrvZgEylR.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`:
```auto
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)
```
---
### Author:  [@hwhsu1231](https://discourse.cmake.org/u/hwhsu1231)
#### Post date: [March 3, 2024, 2:14am UTC](https://discourse.cmake.org/t/suitable-versions-of-sphinx-for-building-different-versions-of-cmake-docs/7982/8 "2024-03-03T02:14:30Z")
> [@brad.king](#):
>
> 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.
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?
---
### Author:  [@ben.boeckel](https://discourse.cmake.org/u/ben.boeckel)
#### Post date: [March 29, 2024, 11:26am UTC](https://discourse.cmake.org/t/suitable-versions-of-sphinx-for-building-different-versions-of-cmake-docs/7982/9 "2024-03-29T11:26:15Z")
> [@hwhsu1231](#):
>
> 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?
---
### Author:  [@hwhsu1231](https://discourse.cmake.org/u/hwhsu1231)
#### Post date: [March 31, 2024, 1:14pm UTC](https://discourse.cmake.org/t/suitable-versions-of-sphinx-for-building-different-versions-of-cmake-docs/7982/10 "2024-03-31T13:14:08Z")
> [@ben.boeckel](#):
>
> 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](https://www.sphinx-doc.org/en/master/usage/advanced/intl.html)), 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](https://docs.python.org/3/))
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](https://discourse.cmake.org/t/how-did-cmake-documentation-deal-with-its-version-switcher-before-v3-9-0/8490), 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.
---
### Author:  [@craig.scott](https://discourse.cmake.org/u/craig.scott)
#### Post date: [March 31, 2024, 11:12pm UTC](https://discourse.cmake.org/t/suitable-versions-of-sphinx-for-building-different-versions-of-cmake-docs/7982/11 "2024-03-31T23:12:46Z")
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).
---
### Author:  [@hwhsu1231](https://discourse.cmake.org/u/hwhsu1231)
#### Post date: [April 1, 2024, 2:49am UTC](https://discourse.cmake.org/t/suitable-versions-of-sphinx-for-building-different-versions-of-cmake-docs/7982/12 "2024-04-01T02:49:26Z")
Hello, @craig.scott
> [@craig.scott](#):
>
> 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.
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.
> [@craig.scott](#):
>
> 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).
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**
>
> ```cmake
> 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()
>
> ```
---
### Author:  [@hwhsu1231](https://discourse.cmake.org/u/hwhsu1231)
#### Post date: [April 19, 2024, 4:58pm UTC](https://discourse.cmake.org/t/suitable-versions-of-sphinx-for-building-different-versions-of-cmake-docs/7982/13 "2024-04-19T16:58:51Z")
Hello, CMake Team.
From the research of this [topic](https://discourse.cmake.org/t/failed-to-translate-the-content-of-parsed-literal-directive-with-hyperlinks-in-cmake-1-rst/10541), it appears that the [issue](https://github.com/sphinx-doc/sphinx/issues/12287) 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.
---
### Author:  [@hwhsu1231](https://discourse.cmake.org/u/hwhsu1231)
#### Post date: [June 7, 2024, 4:45am UTC](https://discourse.cmake.org/t/suitable-versions-of-sphinx-for-building-different-versions-of-cmake-docs/7982/14 "2024-06-07T04:45:00Z")
Hello, CMake Team.
About what @ben.boeckel mentioned previously:
> [@ben.boeckel](#):
>
> (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).
Here is the full log and the screenshot from [vscode-git-graph](https://github.com/mhutchie/vscode-git-graph) of my experimental demo:
> **Click to expand the full log**
>
> ```bash
> 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
>
> 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?
---
### Author:  [@ben.boeckel](https://discourse.cmake.org/u/ben.boeckel)
#### Post date: [June 11, 2024, 4:46pm UTC](https://discourse.cmake.org/t/suitable-versions-of-sphinx-for-building-different-versions-of-cmake-docs/7982/15 "2024-06-11T16:46:13Z")
The topology looks fine to me at a first glance (hard to tell if the merge is `-s ours` or not).
---
### Author:  [@hwhsu1231](https://discourse.cmake.org/u/hwhsu1231)
#### Post date: [April 28, 2025, 2:19pm UTC](https://discourse.cmake.org/t/suitable-versions-of-sphinx-for-building-different-versions-of-cmake-docs/7982/16 "2025-04-28T14:19:01Z")
### Summary of the Previous Content
Hello, CMake Team.
About a year and a half ago, I discussed in this topic the suitable Sphinx versions required to build CMake documentation from version 3.0 to the latest. Through experimentation, I concluded that:
- 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 and sphinx-latest.
In this [reply](https://discourse.cmake.org/t/suitable-versions-of-sphinx-for-building-different-versions-of-cmake-docs/7982/8), I suggested that the team could maintain the documentation for those older CMake versions so that they could be built using the latest Sphinx. At that time, @ben.boeckel mentioned in this [reply](https://discourse.cmake.org/t/suitable-versions-of-sphinx-for-building-different-versions-of-cmake-docs/7982/9) that this could be achieved using `git merge --strategy=ours release-3.0`.
### What I discover now…
Recently, I realized that the errors mainly occur in the `conf.py`, `cmake.py`, and `colors.py` files. So, if I copy those files from the latest version (currently `v4.0.1`) repository, it should probably resolve those build errors.
For example, suppose that I want to use Sphinx version `8.1.3` to build the problematic older CMake documentation. If I place the following three files from the `v4.0.1` version into the corresponding local locations before configuring and building:
- [CMake/Utilities/Sphinx/conf.py.in at v4.0.1 · Kitware/CMake · GitHub](https://github.com/Kitware/CMake/blob/v4.0.1/Utilities/Sphinx/conf.py.in)
- [CMake/Utilities/Sphinx/cmake.py at v4.0.1 · Kitware/CMake · GitHub](https://github.com/Kitware/CMake/blob/v4.0.1/Utilities/Sphinx/cmake.py)
- [CMake/Utilities/Sphinx/colors.py at v4.0.1 · Kitware/CMake · GitHub](https://github.com/Kitware/CMake/blob/v4.0.1/Utilities/Sphinx/colors.py)
Then, the build errors should be resolved. The results after testing prove that the previous fatal errors have disappeared.
Below are the commands I used for demonstration:
> **Click to expand the demo commands for v3.8.2 tag**
>
> ```bash
> # Prepare repository and build environment
> git clone --branch=v3.8.2 --depth=1 https://github.com/Kitware/CMake.git cmake-3.8.2
> cd cmake-3.8.2
> conda create --prefix ./.conda --yes
> conda activate ./.conda
> conda install conda-forge::python=3.12 --channel conda-forge --yes
> export LANG=en_US.UTF-8 LANGUAGE=en_US PYTHONNOUSERSITE=1
> pip install sphinx==8.1.3 --progress-bar=off --verbose
> # Directly configure and build
> cmake -B build -S Utilities/Sphinx -G Ninja -DSPHINX_HTML=ON -DCMAKE_POLICY_VERSION_MINIMUM=3.5
> sphinx-build -b html -c build Help build/html
> # Update those three files before configuring and building
> rm -rf build
> curl -o Utilities/Sphinx/cmake.py https://raw.githubusercontent.com/Kitware/CMake/refs/tags/v4.0.1/Utilities/Sphinx/cmake.py
> curl -o Utilities/Sphinx/colors.py https://raw.githubusercontent.com/Kitware/CMake/refs/tags/v4.0.1/Utilities/Sphinx/colors.py
> curl -o Utilities/Sphinx/conf.py.in https://raw.githubusercontent.com/Kitware/CMake/refs/tags/v4.0.1/Utilities/Sphinx/conf.py.in
> cmake -B build -S Utilities/Sphinx -G Ninja -DSPHINX_HTML=ON -DCMAKE_POLICY_VERSION_MINIMUM=3.5
> sphinx-build -b html -c build Help build/html
> # Open documentation homepage in browser
> firefox build/html/index.html
>
> ```
> **Click to expand the demo commands for v3.18.6 tag**
>
> ```bash
> # Prepare repository and build environment
> git clone --branch=v3.18.6 --depth=1 https://github.com/Kitware/CMake.git cmake-3.18.6
> cd cmake-3.18.6
> conda create --prefix ./.conda --yes
> conda activate ./.conda
> conda install conda-forge::python=3.12 --channel conda-forge --yes
> export LANG=en_US.UTF-8 LANGUAGE=en_US PYTHONNOUSERSITE=1
> pip install sphinx==8.1.3 --progress-bar=off --verbose
> # Directly configure and build
> cmake -B build -S Utilities/Sphinx -G Ninja -DSPHINX_HTML=ON -DCMAKE_POLICY_VERSION_MINIMUM=3.5
> sphinx-build -b html -c build Help build/html
> # Update those three files before configuring and building
> rm -rf build
> curl -o Utilities/Sphinx/cmake.py https://raw.githubusercontent.com/Kitware/CMake/refs/tags/v4.0.1/Utilities/Sphinx/cmake.py
> curl -o Utilities/Sphinx/colors.py https://raw.githubusercontent.com/Kitware/CMake/refs/tags/v4.0.1/Utilities/Sphinx/colors.py
> curl -o Utilities/Sphinx/conf.py.in https://raw.githubusercontent.com/Kitware/CMake/refs/tags/v4.0.1/Utilities/Sphinx/conf.py.in
> cmake -B build -S Utilities/Sphinx -G Ninja -DSPHINX_HTML=ON -DCMAKE_POLICY_VERSION_MINIMUM=3.5
> sphinx-build -b html -c build Help build/html
> # Open documentation homepage in browser
> firefox build/html/index.html
>
> ```
> **Click to expand the demo commands for v3.27.9 tag**
>
> ```bash
> # Prepare repository and build environment
> git clone --branch=v3.27.9 --depth=1 https://github.com/Kitware/CMake.git cmake-3.27.9
> cd cmake-3.27.9
> conda create --prefix ./.conda --yes
> conda activate ./.conda
> conda install conda-forge::python=3.12 --channel conda-forge --yes
> export LANG=en_US.UTF-8 LANGUAGE=en_US PYTHONNOUSERSITE=1
> pip install sphinx==8.1.3 --progress-bar=off --verbose
> # Directly configure and build
> cmake -B build -S Utilities/Sphinx -G Ninja -DSPHINX_HTML=ON -DCMAKE_POLICY_VERSION_MINIMUM=3.5
> sphinx-build -b html -c build Help build/html
> # Update those three files before configuring and building
> rm -rf build
> curl -o Utilities/Sphinx/cmake.py https://raw.githubusercontent.com/Kitware/CMake/refs/tags/v4.0.1/Utilities/Sphinx/cmake.py
> curl -o Utilities/Sphinx/colors.py https://raw.githubusercontent.com/Kitware/CMake/refs/tags/v4.0.1/Utilities/Sphinx/colors.py
> curl -o Utilities/Sphinx/conf.py.in https://raw.githubusercontent.com/Kitware/CMake/refs/tags/v4.0.1/Utilities/Sphinx/conf.py.in
> cmake -B build -S Utilities/Sphinx -G Ninja -DSPHINX_HTML=ON -DCMAKE_POLICY_VERSION_MINIMUM=3.5
> sphinx-build -b html -c build Help build/html
> # Open documentation homepage in browser
> firefox build/html/index.html
>
> ```
I believe this discovery should be very helpful for the “backporting” preparation! If the team decides to backport fixes for those older CMake documentation versions in the future, then they should only need to focus on those three files.