[GIT PULL] Documentation for 6.8

[GIT PULL] Documentation for 6.8

[Jonathan Corbet]

The following changes since commit b85ea95d086471afb4ad062012a4d73cd328fa86:

  Linux 6.7-rc1 (2023-11-12 16:19:07 -0800)

are available in the Git repository at:

  git://git.lwn.net/linux.git tags/docs-6.8

for you to fetch changes up to 2d179e8ac02e33c82c1a314961254353eb5028b3:

  MAINTAINERS: use tabs for indent of CONFIDENTIAL COMPUTING THREAT MODEL (2024-01-08 11:39:00 -0700)

----------------------------------------------------------------
Another moderately busy cycle for documentation, including:

- The minimum Sphinx requirement has been raised to 2.4.4, following a
  warning that was added in 6.2.

- Some reworking of the Documentation/process front page to, hopefully,
  make it more useful.

- Various kernel-doc tweaks to, for example, make it deal properly with
  __counted_by annotations.

- We have also restored a warning for documentation of nonexistent
  structure members that disappeared a while back.  That had the delightful
  consequence of adding some 600 warnings to the docs build.  A sustained
  effort by Randy, Vegard, and myself has addressed almost all of those,
  bringing the documentation back into sync with the code.  The fixes are
  going through the appropriate maintainer trees.

- Various improvements to the HTML rendered docs, including automatic links
  to Git revisions and a nice new pulldown to make translations easy to
  access.

- Speaking of translations, more of those for Spanish and Chinese.

...plus the usual stream of documentation updates and typo fixes.

There is somewhat more than the usual number of merge conflicts, alas,
including with the security, RCU, crypto, and amdgpu trees.  Most of
these are in driver-api/index.rst and userspace-api/index.rst, which are
suffering from the "everybody adds new stuff to the end" problem;
imposing some order there is on my list of things to do.

----------------------------------------------------------------
Alejandro Colomar (1):
      CREDITS, MAINTAINERS, docs/process/howto: Update man-pages' maintainer

Andy Shevchenko (1):
      kernel-doc: Align quick help and the code

Ariel Miculas (1):
      docs: vfs: fix typo in struct xattr_handlers

Avadhut Naik (4):
      docs/sp_SP: Add translation of process/management-style
      docs/sp_SP: Add translation of process/submit-checklist
      docs/sp_SP: Warn of links pointing to documentation in English
      docs/sp_SP: Move howto.rst into /sp_SP/process/

Borislav Petkov (AMD) (1):
      docs: submitting-patches: improve the base commit explanation

Brian Johannesmeyer (1):
      docs: dma-api: Fix description of the sync_sg API

Carlos Bilbao (2):
      docs/sp_SP: Add translation of process/handling-regressions
      MAINTAINERS: add reviewer for Spanish translations

Donald Hunter (1):
      docs: Change <h4> style to use smaller font size than <h3>

Hu Haowen (1):
      docs/zh_TW: replace my email address

Jakub Kicinski (1):
      MAINTAINERS: use tabs for indent of CONFIDENTIAL COMPUTING THREAT MODEL

JiaLong.Yang (1):
      Docs/zh_CN: Fix the meaning of DEBUG to pr_debug()

Jonathan Corbet (4):
      Merge branch 'vegard' into docs-mw
      docs: Raise the minimum Sphinx requirement to 2.4.4
      docs: ignore __counted_by attribute in structure definitions
      A reworked process/index.rst

Kees Cook (2):
      docs: conf.py: Ignore __counted_by attribute
      scripts: kernel-doc: Clarify missing struct member description

Li Zhijian (1):
      docs: dma: update a reference to a moved document

Luca Ceresoli (2):
      docs: nvmem: generate kernel-doc API documentation
      docs: nvmem: remove function parameters (fixes hyperlink generation)

Matthew Cassell (1):
      Documentation/trace: Fixed typos in the ftrace FLAGS section

Randy Dunlap (4):
      fs: vboxsf: fix a kernel-doc warning
      scripts/kernel-doc: restore warning for Excess struct/union
      scripts/get_abi.pl: ignore some temp files
      kernel-doc: handle a void function without producing a warning

Rex Nie (1):
      Documentation: Remove redundant file names from examples

Steven Rostedt (Google) (1):
      ring-buffer/Documentation: Add documentation on buffer_percent file

Sumit Garg (1):
      Documentation: Destage TEE subsystem documentation

Thomas Weißschuh (1):
      Docs: remove mentions of fdformat from util-linux

Vegard Nossum (18):
      docs: style toctree captions as headings
      doc: userspace-api: properly format ToC headings
      media: admin-guide: properly format ToC heading
      crypto: doc: properly format ToC headings
      Documentation: dev-tools: properly format ToC headingss
      docs: driver-api: properly format ToC headings
      input: docs: properly format ToC headings
      doc: misc-device: properly format ToC heading
      media: doc: properly format ToC headings
      docs: use toctree :caption: and move introduction
      docs: remove .toc-title class
      docs: automarkup: linkify git revs
      Documentation: add tux logo
      docs: translations: add translations links when they exist
      scripts/get_abi: fix source path leak
      docs: kernel_abi.py: fix command injection
      Documentation: move driver-api/isapnp to userspace-api/
      Documentation: move driver-api/dcdbas to userspace-api/

Vlastimil Babka (1):
      Documentation, mm/unaccepted: document accept_memory kernel parameter

Yanteng Si (3):
      docs/zh_CN: add process maintainer-pgp-guide tanslation
      docs/zh_CN: Adjust the number of characters per line in magic-number.rst to less than 40
      docs/zh_CN: Update process index to 6.7-rc2

Yuanhsi Chung (1):
      Documentation: Fix filename typo in ftrace doc

attreyee-muk (1):
      Documentation/core-api : fix typo in workqueue

longjin (1):
      Translated the RISC-V architecture boot documentation.

 CREDITS                                            |   7 +
 Documentation/admin-guide/abi-obsolete.rst         |   2 +-
 Documentation/admin-guide/abi-removed.rst          |   2 +-
 Documentation/admin-guide/abi-stable.rst           |   2 +-
 Documentation/admin-guide/abi-testing.rst          |   2 +-
 Documentation/admin-guide/dynamic-debug-howto.rst  |   6 +-
 Documentation/admin-guide/kernel-parameters.txt    |  11 +
 Documentation/admin-guide/media/index.rst          |  10 +-
 Documentation/arch/x86/boot.rst                    |   2 +-
 Documentation/bpf/btf.rst                          |   6 +-
 Documentation/conf.py                              |   9 +-
 Documentation/core-api/dma-api-howto.rst           |   2 +-
 Documentation/core-api/dma-api.rst                 |   2 +-
 Documentation/core-api/workqueue.rst               |   2 +-
 Documentation/crypto/api.rst                       |   5 +-
 Documentation/crypto/index.rst                     |   5 +-
 Documentation/dev-tools/index.rst                  |   5 +-
 Documentation/doc-guide/sphinx.rst                 |  11 +-
 Documentation/driver-api/index.rst                 |   8 +-
 Documentation/driver-api/media/index.rst           |   7 +-
 Documentation/driver-api/mei/index.rst             |   7 +-
 Documentation/driver-api/nvmem.rst                 |   8 +-
 Documentation/driver-api/pci/index.rst             |   5 +-
 Documentation/driver-api/tee.rst                   |  66 ++
 Documentation/filesystems/vfs.rst                  |   2 +-
 Documentation/input/input_kapi.rst                 |   5 +-
 Documentation/input/input_uapi.rst                 |   5 +-
 Documentation/input/joydev/index.rst               |   5 +-
 Documentation/livepatch/callbacks.rst              |   4 +-
 Documentation/misc-devices/index.rst               |   5 +-
 Documentation/networking/snmp_counter.rst          |  16 +-
 Documentation/process/changes.rst                  |   6 +-
 Documentation/process/development-process.rst      |  19 +-
 Documentation/process/howto.rst                    |   3 +-
 Documentation/process/index.rst                    |  84 ++-
 Documentation/process/submitting-patches.rst       |  15 +-
 Documentation/security/keys/trusted-encrypted.rst  |   2 +-
 Documentation/sphinx-static/custom.css             |  63 ++
 Documentation/sphinx-static/theme_overrides.css    |   5 -
 Documentation/sphinx/automarkup.py                 |  26 +-
 Documentation/sphinx/cdomain.py                    |   6 +-
 Documentation/sphinx/kernel_abi.py                 |  56 +-
 Documentation/sphinx/kfigure.py                    |   8 +-
 Documentation/sphinx/templates/translations.html   |  15 +
 Documentation/sphinx/translations.py               | 101 +++
 Documentation/staging/index.rst                    |   1 -
 Documentation/staging/tee.rst                      | 364 ----------
 Documentation/subsystem-apis.rst                   |   1 +
 Documentation/tee/amd-tee.rst                      |  90 +++
 Documentation/tee/index.rst                        |  19 +
 Documentation/tee/op-tee.rst                       | 166 +++++
 Documentation/tee/tee.rst                          |  22 +
 Documentation/trace/ftrace-uses.rst                |   4 +-
 Documentation/trace/ftrace.rst                     |  17 +-
 .../it_IT/process/development-process.rst          |  19 +-
 Documentation/translations/sp_SP/disclaimer-sp.rst |   3 +
 Documentation/translations/sp_SP/index.rst         |   1 -
 .../sp_SP/process/handling-regressions.rst         | 797 +++++++++++++++++++++
 .../translations/sp_SP/{ => process}/howto.rst     |   2 +-
 Documentation/translations/sp_SP/process/index.rst |   4 +
 .../sp_SP/process/management-style.rst             | 299 ++++++++
 .../sp_SP/process/submit-checklist.rst             | 133 ++++
 .../translations/zh_CN/arch/riscv/boot.rst         | 155 ++++
 .../translations/zh_CN/arch/riscv/index.rst        |   1 +
 .../translations/zh_CN/core-api/printk-basics.rst  |   2 +-
 .../translations/zh_CN/dev-tools/index.rst         |   5 +-
 .../zh_CN/dev-tools/testing-overview.rst           |   2 +-
 .../translations/zh_CN/driver-api/gpio/index.rst   |   3 +-
 .../translations/zh_CN/driver-api/index.rst        |   5 +-
 .../zh_CN/process/development-process.rst          |   5 +-
 Documentation/translations/zh_CN/process/index.rst |  53 +-
 .../translations/zh_CN/process/magic-number.rst    |  69 +-
 .../zh_CN/process/maintainer-pgp-guide.rst         | 789 ++++++++++++++++++++
 .../translations/zh_CN/userspace-api/index.rst     |   5 +-
 Documentation/translations/zh_TW/IRQ.txt           |   8 +-
 .../translations/zh_TW/admin-guide/README.rst      |   2 +-
 .../translations/zh_TW/admin-guide/bug-bisect.rst  |   2 +-
 .../translations/zh_TW/admin-guide/bug-hunting.rst |   2 +-
 .../zh_TW/admin-guide/clearing-warn-once.rst       |   2 +-
 .../translations/zh_TW/admin-guide/cpu-load.rst    |   2 +-
 .../translations/zh_TW/admin-guide/index.rst       |   2 +-
 .../translations/zh_TW/admin-guide/init.rst        |   2 +-
 .../zh_TW/admin-guide/reporting-issues.rst         |   2 +-
 .../zh_TW/admin-guide/security-bugs.rst            |   2 +-
 .../zh_TW/admin-guide/tainted-kernels.rst          |   2 +-
 .../translations/zh_TW/admin-guide/unicode.rst     |   2 +-
 .../translations/zh_TW/arch/arm64/amu.rst          |   2 +-
 .../translations/zh_TW/arch/arm64/booting.txt      |   4 +-
 .../translations/zh_TW/arch/arm64/elf_hwcaps.rst   |   2 +-
 .../translations/zh_TW/arch/arm64/hugetlbpage.rst  |   2 +-
 .../translations/zh_TW/arch/arm64/index.rst        |   2 +-
 .../zh_TW/arch/arm64/legacy_instructions.txt       |   4 +-
 .../translations/zh_TW/arch/arm64/memory.txt       |   4 +-
 .../translations/zh_TW/arch/arm64/perf.rst         |   2 +-
 .../zh_TW/arch/arm64/silicon-errata.txt            |   4 +-
 .../zh_TW/arch/arm64/tagged-pointers.txt           |   4 +-
 .../translations/zh_TW/dev-tools/sparse.rst        |  10 +-
 .../zh_TW/dev-tools/testing-overview.rst           |   2 +-
 .../translations/zh_TW/disclaimer-zh_TW.rst        |   2 +-
 .../translations/zh_TW/filesystems/debugfs.rst     |   2 +-
 .../translations/zh_TW/filesystems/index.rst       |   2 +-
 .../translations/zh_TW/filesystems/sysfs.txt       |   2 +-
 .../translations/zh_TW/filesystems/virtiofs.rst    |   2 +-
 Documentation/translations/zh_TW/gpio.txt          |   8 +-
 Documentation/translations/zh_TW/index.rst         |   2 +-
 Documentation/translations/zh_TW/io_ordering.txt   |   8 +-
 .../translations/zh_TW/process/1.Intro.rst         |   2 +-
 .../translations/zh_TW/process/2.Process.rst       |   2 +-
 .../translations/zh_TW/process/3.Early-stage.rst   |   2 +-
 .../translations/zh_TW/process/4.Coding.rst        |   2 +-
 .../translations/zh_TW/process/5.Posting.rst       |   2 +-
 .../translations/zh_TW/process/6.Followthrough.rst |   2 +-
 .../zh_TW/process/7.AdvancedTopics.rst             |   2 +-
 .../translations/zh_TW/process/8.Conclusion.rst    |   2 +-
 .../process/code-of-conduct-interpretation.rst     |   2 +-
 .../translations/zh_TW/process/code-of-conduct.rst |   2 +-
 .../translations/zh_TW/process/coding-style.rst    |   2 +-
 .../zh_TW/process/development-process.rst          |   6 +-
 .../translations/zh_TW/process/email-clients.rst   |   2 +-
 .../zh_TW/process/embargoed-hardware-issues.rst    |   2 +-
 Documentation/translations/zh_TW/process/howto.rst |   2 +-
 Documentation/translations/zh_TW/process/index.rst |   2 +-
 .../zh_TW/process/kernel-driver-statement.rst      |   2 +-
 .../zh_TW/process/kernel-enforcement-statement.rst |   2 +-
 .../translations/zh_TW/process/license-rules.rst   |   2 +-
 .../translations/zh_TW/process/magic-number.rst    |   2 +-
 .../zh_TW/process/management-style.rst             |   2 +-
 .../zh_TW/process/programming-language.rst         |   2 +-
 .../zh_TW/process/stable-api-nonsense.rst          |   2 +-
 .../zh_TW/process/stable-kernel-rules.rst          |   2 +-
 .../zh_TW/process/submit-checklist.rst             |   2 +-
 .../zh_TW/process/submitting-patches.rst           |   2 +-
 .../zh_TW/process/volatile-considered-harmful.rst  |   2 +-
 .../{driver-api => userspace-api}/dcdbas.rst       |   0
 Documentation/userspace-api/index.rst              |   8 +-
 .../{driver-api => userspace-api}/isapnp.rst       |   8 +-
 Documentation/userspace-api/media/cec/cec-api.rst  |   7 +-
 .../userspace-api/media/drivers/index.rst          |   7 +-
 Documentation/userspace-api/media/dvb/dvbapi.rst   |   7 +-
 Documentation/userspace-api/media/index.rst        |   7 +-
 .../media/mediactl/media-controller.rst            |   7 +-
 .../userspace-api/media/rc/remote_controllers.rst  |   7 +-
 Documentation/userspace-api/media/v4l/v4l2.rst     |   7 +-
 Documentation/userspace-api/tee.rst                |  39 +
 MAINTAINERS                                        |  21 +-
 drivers/platform/x86/dell/Kconfig                  |   2 +-
 drivers/platform/x86/dell/dcdbas.c                 |   2 +-
 drivers/pnp/isapnp/Kconfig                         |   2 +-
 drivers/tee/optee/Kconfig                          |   2 +-
 fs/vboxsf/vboxsf_wrappers.c                        |   2 +-
 scripts/get_abi.pl                                 |   3 +-
 scripts/kernel-doc                                 |  15 +-
 scripts/sphinx-pre-install                         |  10 +-
 153 files changed, 3206 insertions(+), 794 deletions(-)
 create mode 100644 Documentation/driver-api/tee.rst
 create mode 100644 Documentation/sphinx/templates/translations.html
 create mode 100644 Documentation/sphinx/translations.py
 delete mode 100644 Documentation/staging/tee.rst
 create mode 100644 Documentation/tee/amd-tee.rst
 create mode 100644 Documentation/tee/index.rst
 create mode 100644 Documentation/tee/op-tee.rst
 create mode 100644 Documentation/tee/tee.rst
 create mode 100644 Documentation/translations/sp_SP/process/handling-regressions.rst
 rename Documentation/translations/sp_SP/{ => process}/howto.rst (99%)
 create mode 100644 Documentation/translations/sp_SP/process/management-style.rst
 create mode 100644 Documentation/translations/sp_SP/process/submit-checklist.rst
 create mode 100644 Documentation/translations/zh_CN/arch/riscv/boot.rst
 create mode 100644 Documentation/translations/zh_CN/process/maintainer-pgp-guide.rst
 rename Documentation/{driver-api => userspace-api}/dcdbas.rst (100%)
 rename Documentation/{driver-api => userspace-api}/isapnp.rst (51%)
 create mode 100644 Documentation/userspace-api/tee.rst

Re: [GIT PULL] Documentation for 6.8

[pr-tracker-bot]

The pull request you sent on Mon, 08 Jan 2024 11:59:24 -0700:

> git://git.lwn.net/linux.git tags/docs-6.8

has been merged into torvalds/linux.git:
https://git.kernel.org/torvalds/c/5b9b41617bf3e1282cc60f07d3d52e62399aa4ba

Thank you!

-- 
Deet-doot-dot, I am a bot.
https://korg.docs.kernel.org/prtracker.html

Re: [GIT PULL] Documentation for 6.8

[Linus Torvalds]

On Mon, 8 Jan 2024 at 10:59, Jonathan Corbet <corbet@lwn.net> wrote:
>
> - The minimum Sphinx requirement has been raised to 2.4.4, following a
>   warning that was added in 6.2.

Well, speaking of warnings, github now has this "dependabot" thing
that warns about bad minimum requirements due to tooling that has
security issues.

And it warns about our "jinja2 < 3.1" requirement, because apparently
that can cause issues:

  "The xmlattr filter in affected versions of Jinja accepts keys
containing spaces. XML/HTML attributes cannot contain spaces, as each
would then be interpreted as a separate attribute. If an application
accepts keys (as opposed to only values) as user input, and renders
these in pages that other users see as well, an attacker could use
this to inject other attributes and perform XSS. Note that accepting
keys as user input is not common or a particularly intended use case
of the xmlattr filter, and an application doing so should already be
verifying what keys are provided regardless of this fix"

with affected versions being marked as < 3.1.3 and fixed in Jinja2 3.1.3

I'm ignoring this github dependabit warning since the issue seems to
be rather irrelevant for our doc use, but I thought I'd mention it.

            Linus

Re: [GIT PULL] Documentation for 6.8

[Jonathan Corbet]

[Adding Akira]

Linus Torvalds <torvalds@linuxfoundation.org> writes:

> On Mon, 8 Jan 2024 at 10:59, Jonathan Corbet <corbet@lwn.net> wrote:
>>
>> - The minimum Sphinx requirement has been raised to 2.4.4, following a
>>   warning that was added in 6.2.
>
> Well, speaking of warnings, github now has this "dependabot" thing
> that warns about bad minimum requirements due to tooling that has
> security issues.
>
> And it warns about our "jinja2 < 3.1" requirement, because apparently
> that can cause issues:
>
>   "The xmlattr filter in affected versions of Jinja accepts keys
> containing spaces. XML/HTML attributes cannot contain spaces, as each
> would then be interpreted as a separate attribute. If an application
> accepts keys (as opposed to only values) as user input, and renders
> these in pages that other users see as well, an attacker could use
> this to inject other attributes and perform XSS. Note that accepting
> keys as user input is not common or a particularly intended use case
> of the xmlattr filter, and an application doing so should already be
> verifying what keys are provided regardless of this fix"
>
> with affected versions being marked as < 3.1.3 and fixed in Jinja2 3.1.3
>
> I'm ignoring this github dependabit warning since the issue seems to
> be rather irrelevant for our doc use, but I thought I'd mention it.

I suppose it is worth looking into this, just in case a hostile docs
patch that nobody catches might somehow cause an exploit to show up on
docs.kernel.org.  Seems unlikely but it would be good to be sure.

Akira (CC'd) noted, in adding that requirement, that newer jinja2 breaks
Sphinx prior to 4.8.  I've been thinking that supporting 2.x is going to
prove increasingly unsustainable, but raising our minimum to 4.8 would
surely make some people unhappy.

I like the Python ecosystem for a lot of things, but its approach to API
compatibility is ... not great.

jon

Re: [GIT PULL] Documentation for 6.8

[Akira Yokosawa]

On Fri, 12 Jan 2024 07:43:39 -0700, Jonathan Corbet wrote:
> [Adding Akira]

Thanks!

> 
> Linus Torvalds <torvalds@linuxfoundation.org> writes:
> 
>> On Mon, 8 Jan 2024 at 10:59, Jonathan Corbet <corbet@lwn.net> wrote:
>>>
>>> - The minimum Sphinx requirement has been raised to 2.4.4, following a
>>>   warning that was added in 6.2.
>>
>> Well, speaking of warnings, github now has this "dependabot" thing
>> that warns about bad minimum requirements due to tooling that has
>> security issues.
>>
>> And it warns about our "jinja2 < 3.1" requirement, because apparently
>> that can cause issues:
>>
>>   "The xmlattr filter in affected versions of Jinja accepts keys
>> containing spaces. XML/HTML attributes cannot contain spaces, as each
>> would then be interpreted as a separate attribute. If an application
>> accepts keys (as opposed to only values) as user input, and renders
>> these in pages that other users see as well, an attacker could use
>> this to inject other attributes and perform XSS. Note that accepting
>> keys as user input is not common or a particularly intended use case
>> of the xmlattr filter, and an application doing so should already be
>> verifying what keys are provided regardless of this fix"
>>
>> with affected versions being marked as < 3.1.3 and fixed in Jinja2 3.1.3
>>
>> I'm ignoring this github dependabit warning since the issue seems to
>> be rather irrelevant for our doc use, but I thought I'd mention it.
> 
> I suppose it is worth looking into this, just in case a hostile docs
> patch that nobody catches might somehow cause an exploit to show up on
> docs.kernel.org.  Seems unlikely but it would be good to be sure.
> 
> Akira (CC'd) noted, in adding that requirement, that newer jinja2 breaks
> Sphinx prior to 4.8.

There has never been a release "Sphinx 4.8".

What I said in [1] was:

 # jinja2>=3.1 is not compatible with Sphinx<4.0
 jinja2<3.1
-Sphinx==2.4.4
+# docutils>=0.18 is not compatible with 3.0 <= Sphinx < 4.0
+docutils<0.18
+Sphinx==3.4.3

So newer jinja2 and docutils break Sphinx prior to 4.0.

One more inconvenient truth Jon wouldn't like to know.

Official python 3.10 support was new to Sphinx 4.3.
So, I guess reasonable version for recommending is Sphinx>=4.3.

But at the same time, The latest Sphinx 7.2.6 works only with
python>=3.9.  If your base python3 is 3.8 (e.g. ubuntu 20.04),
you can't have the latest one.

Sounds very complicated, doesn't it?

I'm beginning to think that we can forget about those subtle
incompatibilities by recommending distro Sphinx packages.

As I summarized in [2], RHEL 9 and debian 11 have Sphinx 3.4.3,
which is good enough for kernel documentation.
Quoting from [2]:

              As of 2023.11.30

    ----------------------------------
    Distro              Sphinx Python3
    =================== ====== =======
    Ubuntu 22.04 LTS    4.3.2  3.10.12
    Debian 11           3.4.3  3.9.2
    Debian 12           5.3.0  3.11.2
    Fedora 39           6.2.1  3.12.0
    RHEL 9              3.4.3  3.9.18
    Mageia 9            6.1.3  3.10.11
    openSUSE Leap 15.5  4.2.0  3.6.15  (provided as python3-Sphinx_4_2_0)
    ----------------------------------

Installing one of those packages should come with compatible
requirements, plus several security fixes backported if we are
lucky.

There was a time when distro Sphinx was <2.4 and wasn't usable
for kernel documentation.  It is no longer true anymore.

[1]: https://lore.kernel.org/linux-doc/50830030-dca7-4c43-bcc8-449c7cfa9fbb@gmail.com/
[2]: https://lore.kernel.org/linux-doc/c3accd5b-c8d9-4eb9-86a1-054e89893a8f@gmail.com/

        Thanks, Akira


  I've been thinking that supporting 2.x is going to
> prove increasingly unsustainable, but raising our minimum to 4.8 would
> surely make some people unhappy.
> 
> I like the Python ecosystem for a lot of things, but its approach to API
> compatibility is ... not great.
> 
> jon

Re: [GIT PULL] Documentation for 6.8

[Matthew Wilcox]

On Sat, Jan 13, 2024 at 12:28:44AM +0900, Akira Yokosawa wrote:
> Official python 3.10 support was new to Sphinx 4.3.
> So, I guess reasonable version for recommending is Sphinx>=4.3.
> 
> But at the same time, The latest Sphinx 7.2.6 works only with
> python>=3.9.  If your base python3 is 3.8 (e.g. ubuntu 20.04),
> you can't have the latest one.

I don't know that I care about Ubuntu 20.04; that's almost 4 years old and
probably isn't being used by anyone who's building kernel documentation.

Oracle Linux 9 (2022) ships Python 3.9.14.  It also appears to ship python
3.11.2 as an optional install.  It doesn't seem to ship sphinx at all.
At least not that I can find from a quick rummage in the repositories.
The recommendation I'm finding is to use pip to install sphinx if you
need it.

Re: [GIT PULL] Documentation for 6.8

[Akira Yokosawa]

Hi Willy,

On 2024/01/13 1:09, Matthew Wilcox wrote:
> On Sat, Jan 13, 2024 at 12:28:44AM +0900, Akira Yokosawa wrote:
>> Official python 3.10 support was new to Sphinx 4.3.
>> So, I guess reasonable version for recommending is Sphinx>=4.3.
>>
>> But at the same time, The latest Sphinx 7.2.6 works only with
>> python>=3.9.  If your base python3 is 3.8 (e.g. ubuntu 20.04),
>> you can't have the latest one.
> 
> I don't know that I care about Ubuntu 20.04; that's almost 4 years old and
> probably isn't being used by anyone who's building kernel documentation.
> 
> Oracle Linux 9 (2022) ships Python 3.9.14.  It also appears to ship python
> 3.11.2 as an optional install.  It doesn't seem to ship sphinx at all.
> At least not that I can find from a quick rummage in the repositories.
> The recommendation I'm finding is to use pip to install sphinx if you
> need it.
> 

Oracle Linux 9 has the same version as RHEL/CentOS/Alma/Rocky 9
by the package name of python3-sphinx in the ol9_codeready_builder
repo.  You need to enable it by saying:

    dnf --enablerepo=ol9_codeready_builder install python3-sphinx

HTH,

Akira