Failed to build the HTML documentation of Linux Kernel

hwhsu1231 · 03-14-2024, 11:23 PM

Hello, Linux Questions Forum.

Recently, I tried to build the HTML documentation of Linux Kernel. However, I met an error when buliding the master version.

Therefore, I posted an issue in sphinx-doc. And then, I got a reponse to report the issue to Linux Kernel repo.

Later, I noticed that the official documentation is '6.8.0' version, so I tried to build documentation from v6.8 tag. But it failed with the depencendies error:

Code:

(.venv) hwhsu1231@vb-kubuntu:~/Repo/testing/linux/Documentation$ LANG=en_US.UTF-8 sphinx-build -b html -c . . _build/html
Running Sphinx v2.4.4
Using alabaster theme
loading translations [en]... done
WARNING: while setting up extension sphinx.addnodes: node class 'meta' is already registered, its visitors will be overridden

Sphinx version error:
The sphinxcontrib.applehelp extension used by this project needs at least Sphinx v5.0; it therefore cannot be built with this version.

Later, I noticed that the official documentation told us to use 'make htmldocs' command to build the documentation. But, it failed with another error:

Code:

(.venv) hwhsu1231@vb-kubuntu:~/Repo/testing/linux/Documentation$ make htmldocs
/tools/net/ynl/ynl-gen-rst.py -o /Documentation/networking/netlink_spec/index.rst -x
make: /tools/net/ynl/ynl-gen-rst.py: No such file or directory
make: *** [Makefile:109: /Documentation/networking/netlink_spec/index.rst] Error 127

Can someone help me to figure out what happened? How to fix it? Thanks!

The following is the full log:

Code:

hwhsu1231@vb-kubuntu:~/Repo/testing$ git clone --depth=1 --branch=v6.8 https://github.com/torvalds/linux.git
Cloning into 'linux'...
remote: Enumerating objects: 88457, done.
remote: Counting objects: 100% (88457/88457), done.
remote: Compressing objects: 100% (79411/79411), done.
remote: Total 88457 (delta 8880), reused 68852 (delta 8133), pack-reused 0
Receiving objects: 100% (88457/88457), 245.74 MiB | 2.11 MiB/s, done.
Resolving deltas: 100% (8880/8880), done.
Note: switching to 'e8f897f4afef0031fe618a8e94127a0934896aba'.

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

Updating files: 100% (83475/83475), done.
hwhsu1231@vb-kubuntu:~/Repo/testing$ cd linux
hwhsu1231@vb-kubuntu:~/Repo/testing/linux$ python3 -m venv .venv
hwhsu1231@vb-kubuntu:~/Repo/testing/linux$ source .venv/bin/activate
(.venv) hwhsu1231@vb-kubuntu:~/Repo/testing/linux$ cd Documentation
(.venv) hwhsu1231@vb-kubuntu:~/Repo/testing/linux/Documentation$ pip install -r sphinx/requirements.txt
Collecting jinja2<3.1
  Using cached Jinja2-3.0.3-py3-none-any.whl (133 kB)
Collecting alabaster<0.7.14
  Using cached alabaster-0.7.13-py3-none-any.whl (13 kB)
Collecting Sphinx==2.4.4
  Using cached Sphinx-2.4.4-py3-none-any.whl (2.7 MB)
Collecting pyyaml
  Using cached PyYAML-6.0.1-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (705 kB)
Collecting imagesize
  Using cached imagesize-1.4.1-py2.py3-none-any.whl (8.8 kB)
Requirement already satisfied: setuptools in /home/hwhsu1231/Repo/testing/linux/.venv/lib/python3.10/site-packages (from Sphinx==2.4.4->-r sphinx/requirements.txt (line 5)) (59.6.0)
Collecting babel!=2.0,>=1.3
  Using cached Babel-2.14.0-py3-none-any.whl (11.0 MB)
Collecting sphinxcontrib-serializinghtml
  Using cached sphinxcontrib_serializinghtml-1.1.10-py3-none-any.whl (92 kB)
Collecting Pygments>=2.0
  Using cached pygments-2.17.2-py3-none-any.whl (1.2 MB)
Collecting sphinxcontrib-qthelp
  Using cached sphinxcontrib_qthelp-1.0.7-py3-none-any.whl (89 kB)
Collecting sphinxcontrib-applehelp
  Using cached sphinxcontrib_applehelp-1.0.8-py3-none-any.whl (120 kB)
Collecting packaging
  Using cached packaging-24.0-py3-none-any.whl (53 kB)
Collecting sphinxcontrib-devhelp
  Using cached sphinxcontrib_devhelp-1.0.6-py3-none-any.whl (83 kB)
Collecting snowballstemmer>=1.1
  Using cached snowballstemmer-2.2.0-py2.py3-none-any.whl (93 kB)
Collecting sphinxcontrib-jsmath
  Using cached sphinxcontrib_jsmath-1.0.1-py2.py3-none-any.whl (5.1 kB)
Collecting docutils>=0.12
  Using cached docutils-0.20.1-py3-none-any.whl (572 kB)
Collecting requests>=2.5.0
  Using cached requests-2.31.0-py3-none-any.whl (62 kB)
Collecting sphinxcontrib-htmlhelp
  Using cached sphinxcontrib_htmlhelp-2.0.5-py3-none-any.whl (99 kB)
Collecting MarkupSafe>=2.0
  Using cached MarkupSafe-2.1.5-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (25 kB)
Collecting urllib3<3,>=1.21.1
  Using cached urllib3-2.2.1-py3-none-any.whl (121 kB)
Collecting certifi>=2017.4.17
  Using cached certifi-2024.2.2-py3-none-any.whl (163 kB)
Collecting idna<4,>=2.5
  Using cached idna-3.6-py3-none-any.whl (61 kB)
Collecting charset-normalizer<4,>=2
  Using cached charset_normalizer-3.3.2-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (142 kB)
Installing collected packages: snowballstemmer, urllib3, sphinxcontrib-serializinghtml, sphinxcontrib-qthelp, sphinxcontrib-jsmath, sphinxcontrib-htmlhelp, sphinxcontrib-devhelp, sphinxcontrib-applehelp, pyyaml, Pygments, packaging, MarkupSafe, imagesize, idna, docutils, charset-normalizer, certifi, babel, alabaster, requests, jinja2, Sphinx
Successfully installed MarkupSafe-2.1.5 Pygments-2.17.2 Sphinx-2.4.4 alabaster-0.7.13 babel-2.14.0 certifi-2024.2.2 charset-normalizer-3.3.2 docutils-0.20.1 idna-3.6 imagesize-1.4.1 jinja2-3.0.3 packaging-24.0 pyyaml-6.0.1 requests-2.31.0 snowballstemmer-2.2.0 sphinxcontrib-applehelp-1.0.8 sphinxcontrib-devhelp-1.0.6 sphinxcontrib-htmlhelp-2.0.5 sphinxcontrib-jsmath-1.0.1 sphinxcontrib-qthelp-1.0.7 sphinxcontrib-serializinghtml-1.1.10 urllib3-2.2.1
(.venv) hwhsu1231@vb-kubuntu:~/Repo/testing/linux/Documentation$ LANG=en_US.UTF-8 sphinx-build -b html -c . . _build/html
Running Sphinx v2.4.4
Using alabaster theme
loading translations [en]... done
WARNING: while setting up extension sphinx.addnodes: node class 'meta' is already registered, its visitors will be overridden

Sphinx version error:
The sphinxcontrib.applehelp extension used by this project needs at least Sphinx v5.0; it therefore cannot be built with this version.
(.venv) hwhsu1231@vb-kubuntu:~/Repo/testing/linux/Documentation$ make htmldocs
/tools/net/ynl/ynl-gen-rst.py -o /Documentation/networking/netlink_spec/index.rst -x
make: /tools/net/ynl/ynl-gen-rst.py: No such file or directory
make: *** [Makefile:109: /Documentation/networking/netlink_spec/index.rst] Error 127
(.venv) hwhsu1231@vb-kubuntu:~/Repo/testing/linux/Documentation$