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

**URL:** https://discourse.cmake.org/t/suitable-versions-of-sphinx-for-building-different-versions-of-cmake-docs/7982
**Category:** Development
**Created:** [April 25, 2023, 5:01pm UTC](https://discourse.cmake.org/t/suitable-versions-of-sphinx-for-building-different-versions-of-cmake-docs/7982 "2023-04-25T17:01:33Z")
**Posts on this page:** 1
**Showing post:** 1

<div class="post-metadata">

### Author: ![hwhsu1231](https://discourse.cmake.org/user_avatar/discourse.cmake.org/hwhsu1231/32/5358_2.png) [@hwhsu1231](https://discourse.cmake.org/u/hwhsu1231)
#### Post date: [April 25, 2023, 5:01pm UTC](https://discourse.cmake.org/t/suitable-versions-of-sphinx-for-building-different-versions-of-cmake-docs/7982/1 "2023-04-25T17:01:33Z")

</div>

Recently, I tried to configure and build the [`CMakeHelp`](https://github.com/Kitware/CMake/blob/v3.26.3/Utilities/Sphinx/CMakeLists.txt#L19) 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:

```plaintext
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:

```auto
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**
>
> ```plaintext
> 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

---

_[View the full topic](https://discourse.cmake.org/t/suitable-versions-of-sphinx-for-building-different-versions-of-cmake-docs/7982)._