The automarkup code tries to create a lot of cross-references that don't
exist.  Cross-reference lookups are expensive, especially in later versions
of Sphinx, so there is value in avoiding unnecessary ones.  Remember
attempts that failed and do not retry them.

This improves the htmldocs build time by 5-10% depending on the phase of
the moon and other factors.
Tested-by: Akira Yokosawa <akiyks@gmail.com>
Link: https://lore.kernel.org/r/20220630163630.714673-2-corbet@lwn.netSigned-off-by: Jonathan Corbet <corbet@lwn.net>

All extern functions of drivers/gpio/gpiolib.c are already
inside the Kernel documentation, as driver-api/gpio/index.rst
already includes it.

Placing a kernel-doc here will only cause mess, as the same symbol
will be placed on two parts of the document, causing breakages
in cross-references.

So, instead, add a cross-reference there.

This solves those Sphinx 3.1+ warnings:
    .../Documentation/driver-api/hte/tegra194-hte:28: ./drivers/gpio/gpiolib.c:2464: WARNING: Duplicate C declaration, also defined at driver-api/gpio/index:2464.
    .../Documentation/driver-api/hte/tegra194-hte:28: ./drivers/gpio/gpiolib.c:2493: WARNING: Duplicate C declaration, also defined at driver-api/gpio/index:2493.
    .../Documentation/driver-api/hte/tegra194-hte.rst:2464: WARNING: Duplicate C declaration, also defined at driver-api/gpio/index:2464.
    .../Documentation/driver-api/hte/tegra194-hte.rst:2464: WARNING: Duplicate C declaration, also defined at driver-api/gpio/index:2464.
    .../Documentation/driver-api/hte/tegra194-hte.rst:2464: WARNING: Duplicate C declaration, also defined at driver-api/gpio/index:2464.
    .../Documentation/driver-api/hte/tegra194-hte.rst:2493: WARNING: Duplicate C declaration, also defined at driver-api/gpio/index:2493.
    .../Documentation/driver-api/hte/tegra194-hte.rst:2493: WARNING: Duplicate C declaration, also defined at driver-api/gpio/index:2493.
    .../Documentation/driver-api/hte/tegra194-hte.rst:2493: WARNING: Duplicate C declaration, also defined at driver-api/gpio/index:2493.
Signed-off-by: Mauro Carvalho Chehab <mchehab@kernel.org>
Link: https://lore.kernel.org/r/de81b472f552bd651f140f0aa779a29652fffa62.1656759989.git.mchehab@kernel.orgAcked-by: Dipen Patel <dipenp@nvidia.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Newer versions of Sphinx have a known bug:
	https://github.com/sphinx-doc/sphinx/pull/8313

Those currently produces 11 false-positive warnings On Sphinx
version 3.1+.

While Sphinx fix is not applied, let's warn adventurers that would
be using Sphinx installed via distro packages.
Signed-off-by: Mauro Carvalho Chehab <mchehab@kernel.org>
Link: https://lore.kernel.org/r/085e0ada65c11da9303d07e70c510dc45f21315b.1656756450.git.mchehab@kernel.orgSigned-off-by: Jonathan Corbet <corbet@lwn.net>

As it is not a consensus about installing sphinx using venv, and
modern distributions are now shipping with Sphinx versions above
the minimal requirements to build the docs, provide both venv
and package install commands by default.
Signed-off-by: Mauro Carvalho Chehab <mchehab@kernel.org>
Link: https://lore.kernel.org/r/7c99d985df204c73e3daafd5fd2f30a31269405d.1656756450.git.mchehab@kernel.orgSigned-off-by: Jonathan Corbet <corbet@lwn.net>

Better to add the PDF note late for venv recommendation.
Signed-off-by: Mauro Carvalho Chehab <mchehab@kernel.org>
Link: https://lore.kernel.org/r/8e117aabe6dfa1b1ec92dccd20e801393c977667.1656756450.git.mchehab@kernel.orgSigned-off-by: Jonathan Corbet <corbet@lwn.net>

After distro upgrades, the directory names for python may change.
On such case, the previously-created venv will be broken, and
sphinx-build won't run.

Add a logic to report it.
Signed-off-by: Mauro Carvalho Chehab <mchehab@kernel.org>
Link: https://lore.kernel.org/r/f117f03555b0636d2be0b68f3a23b1d3f03ccf1d.1656756450.git.mchehab@kernel.org
[jc: fixed typo in warning message]
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

The logic which checks if the venv version is good enough
but was not activated is broken: it is checking against
the wrong val, making it to recommend to re-create a venv
every time. Fix it.
Signed-off-by: Mauro Carvalho Chehab <mchehab@kernel.org>
Link: https://lore.kernel.org/r/afe01b7863fd655986d84ace8948f3d7aede796d.1656756450.git.mchehab@kernel.orgSigned-off-by: Jonathan Corbet <corbet@lwn.net>

SPHINXDIRS is useful when you want to test build only those
documents affected by your changes.

Mention it in the "Sphinx Build" section.
Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
Cc: Maciej W. Rozycki <macro@orcam.me.uk>
Link: https://lore.kernel.org/r/50d6f0bc-030d-9529-0665-e2b3e7c792d8@gmail.comSigned-off-by: Jonathan Corbet <corbet@lwn.net>

I tried running `make pdfdocs` on NixOS, but it failed because
get_feat.pl uses a shebang line with /usr/bin/perl, and that file path
doesn't exist on NixOS. Using the more portable /usr/bin/env perl fixes
the problem.
Signed-off-by: David Reaver <me@davidreaver.com>
Link: https://lore.kernel.org/r/20220625211548.1200198-1-me@davidreaver.comSigned-off-by: Jonathan Corbet <corbet@lwn.net>

Translate locking/mutex-design.rst into Chinese.
Signed-off-by: Tang Yizhou <yizhou.tang@shopee.com>
Reviewed-by: Alex Shi <alexs@kernel.org>
Reviewed-by: Yanteng Si<siyanteng@loongson.cn>
Link: https://lore.kernel.org/r/20220629013240.65386-3-yizhou.tang@shopee.comSigned-off-by: Jonathan Corbet <corbet@lwn.net>

Last time I forgot to edit locking/index.rst so the Chinese translation
of spinlocks hasn't been shown on web yet.
Signed-off-by: Tang Yizhou <yizhou.tang@shopee.com>
Reviewed-by: Yanteng Si<siyanteng@loongson.cn>
Reviewed-by: Alex Shi <alexs@kernel.org>
Link: https://lore.kernel.org/r/20220629013240.65386-2-yizhou.tang@shopee.comSigned-off-by: Jonathan Corbet <corbet@lwn.net>

kernel-doc.rst has two 1st level section titles of "Writing
kernel-doc comments" and "Including kernel-doc comments".

Therefore, rather than using the first one, put a meta title
of "Kernel-doc comments" for the title of the resulting HTML
page by using the "title" directive.
Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
Link: https://lore.kernel.org/r/15636c13-7fa2-f973-6d3d-361222b839ef@gmail.comSigned-off-by: Jonathan Corbet <corbet@lwn.net>

With kernel releases v5.18 and later, if you have Inkscape, images
embedded in PDF documents are of vector graphics, not the raster
images as are the case with pre-v5.18 releases.
Even with pre-5.18 releases, having Inkscape would improve images
converted from some of SVG files which are not fully covered by the
limited capability of rsvg-convert(1) [1].

Add a footnote mentioning the expected improvements of such images.

Link: https://gitlab.gnome.org/GNOME/librsvg#non-goals-of-librsvg [1]
Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
Link: https://lore.kernel.org/r/81cddbde-bc28-bec1-fca4-3c8fe2df502f@gmail.comSigned-off-by: Jonathan Corbet <corbet@lwn.net>

Improve and add instructions to add new tests. Add build commands to
test before sending the new test patch.
Signed-off-by: Muhammad Usama Anjum <usama.anjum@collabora.com>
Reviewed-by: Shuah Khan <skhan@linuxfoundation.org>
Link: https://lore.kernel.org/r/20220521073651.4191910-1-usama.anjum@collabora.comSigned-off-by: Jonathan Corbet <corbet@lwn.net>

* update to commit f35cf1a5 ("Documentation: kernel-hacking: minor
  edits for style")

* fix a homophone typo reported by Li Feng
Reported-by: Li Feng <felixlee868@icloud.com>
Signed-off-by: Wu XiangCheng <bobwxc@email.cn>
Reviewed-by: Yanteng Si <siyanteng@loongson.cn>
Link: https://lore.kernel.org/r/Yp41+eTjoPRa4hrl@bobwxc.mipcSigned-off-by: Jonathan Corbet <corbet@lwn.net>

Translate .../vm/vmalloced-kernel-stacks.rst into Chinese.
Signed-off-by: Yanteng Si <siyanteng@loongson.cn>
Reviewed-by: Wu XiangCheng <bobwxc@email.cn>
Link: https://lore.kernel.org/r/01de54c7ecfd1999a636ee59ac40b79917251af2.1654585011.git.siyanteng@loongson.cnSigned-off-by: Jonathan Corbet <corbet@lwn.net>

Translate .../vm/page_migration.rst into Chinese.
Signed-off-by: Yanteng Si <siyanteng@loongson.cn>
Reviewed-by: Wu XiangCheng <bobwxc@email.cn>
Link: https://lore.kernel.org/r/44bc4486e5019f689bcbec20a629a9f7800ece33.1654585011.git.siyanteng@loongson.cnSigned-off-by: Jonathan Corbet <corbet@lwn.net>

Synchronous translation from upstream commit 9d19f2b5
("Documentation: riscv: Add sv48 description to VM layout")
Signed-off-by: Binbin Zhou <zhoubinbin@loongson.cn>
Reviewed-by: Yanteng Si <siyanteng@loongson.cn>
Reviewed-by: Wu XiangCheng <bobwxc@email.cn>
Link: https://lore.kernel.org/r/10cd6a241a0266d1d19ee5f0b2177d7d14d17ed2.1654685338.git.zhoubinbin@loongson.cnSigned-off-by: Jonathan Corbet <corbet@lwn.net>

Synchronous translation from the following:

[1]: commit 23b1f183("Documentation: riscv:
     Remove the old documentation")

[2]: commit 8933e7f2 ("Documentation: riscv: remove
     non-existent directory from table of contents")
Signed-off-by: Binbin Zhou <zhoubinbin@loongson.cn>
Reviewed-by: Yanteng Si <siyanteng@loongson.cn>
Reviewed-by: Wu XiangCheng <bobwxc@email.cn>
Link: https://lore.kernel.org/r/6fe45d69210300a6c065262470bce963f8dc0ec3.1654685338.git.zhoubinbin@loongson.cnSigned-off-by: Jonathan Corbet <corbet@lwn.net>

Fix the invalid url about Semantic Patch Language
Signed-off-by: Dongliang Mu <mudongliangabcd@gmail.com>
Link: https://lore.kernel.org/r/20220613071243.12961-1-dzm91@hust.edu.cnSigned-off-by: Jonathan Corbet <corbet@lwn.net>

Since commit c6140415 ("f2fs: introduce FI_COMPRESS_RELEASED
instead of using IMMUTABLE bit"), we no longer use the IMMUTABLE
bit to prevent writing data for compression. Let's correct the
corresponding documentation.

BTW, this patch fixes some alignment issues in the compress
metadata layout.
Signed-off-by: Chao Liu <liuchao@coolpad.com>
Link: https://lore.kernel.org/r/20220613020800.3379482-1-chaoliu719@gmail.comSigned-off-by: Jonathan Corbet <corbet@lwn.net>

update to commit 481cc973 ("mm,doc: Add new
documentation structure")

Note: There are some empty files that do not need to be updated for now,
they are:

bootmem,
oom,
page_allocation,
page_cache,
page_reclaim,
page_tables,
physical_memory
process_addrs,
shmfs,
slab,
vmalloc,
swap.
Signed-off-by: Yanteng Si <siyanteng@loongson.cn>
Reviewed-by: Wu XiangCheng <bobwxc@email.cn>
Reviewed-by: Alex Shi <alexs@kernel.org>
Link: https://lore.kernel.org/r/35d10864fb9b57bf288d4efa5642f93a60079029.1655362610.git.siyanteng@loongson.cnSigned-off-by: Jonathan Corbet <corbet@lwn.net>

update to commit d1ed51fc ("docs: vm/page_owner: tweak
literal block in STANDARD FORMAT SPECIFIERS")
Signed-off-by: Yanteng Si <siyanteng@loongson.cn>
Reviewed-by: Wu XiangCheng <bobwxc@email.cn>
Reviewed-by: Alex Shi <alexs@kernel.org>
Link: https://lore.kernel.org/r/e96557b73b036c33a9fa5abdab0c541704235e92.1655362610.git.siyanteng@loongson.cnSigned-off-by: Jonathan Corbet <corbet@lwn.net>

update to commit 110bf7a5 ("Documentation/vm: rework
"Temporary Virtual Mappings" section")
Signed-off-by: Yanteng Si <siyanteng@loongson.cn>
Reviewed-by: Wu XiangCheng <bobwxc@email.cn>
Reviewed-by: Alex Shi <alexs@kernel.org>
Link: https://lore.kernel.org/r/76c418554d9b8d395f7e8331e8e3b89d1b7beff0.1655362610.git.siyanteng@loongson.cnSigned-off-by: Jonathan Corbet <corbet@lwn.net>

Replace 'absense' with 'absence'.
Signed-off-by: Steven Lung <1030steven@gmail.com>
Link: https://lore.kernel.org/r/20220621072910.4704-1-1030steven@gmail.comSigned-off-by: Jonathan Corbet <corbet@lwn.net>

Synchronous translation from upstream commit ac23d1a9
("XArray: Document the locking requirement for the xa_state")
Signed-off-by: Binbin Zhou <zhoubinbin@loongson.cn>
Reviewed-by: Wu XiangCheng <bobwxc@email.cn>
Reviewed-by: Yanteng Si<siyanteng@loongson.cn>
Link: https://lore.kernel.org/r/b7d5f3ca914667ec14ba35a7c0db3ec3506e670d.1655863769.git.zhoubinbin@loongson.cnSigned-off-by: Jonathan Corbet <corbet@lwn.net>

Synchronous translation from upstream commit f9eaaa82
("workqueue: doc: Call out the non-reentrance conditions")
Signed-off-by: Binbin Zhou <zhoubinbin@loongson.cn>
Reviewed-by: Wu XiangCheng <bobwxc@email.cn>
Reviewed-by: Yanteng Si<siyanteng@loongson.cn>
Link: https://lore.kernel.org/r/d045cb5623b5ae703c2296d3caa05017d5d225bd.1655863769.git.zhoubinbin@loongson.cnSigned-off-by: Jonathan Corbet <corbet@lwn.net>

Synchronous translation from upstream commit 6a7ca80f
("vsprintf: Update %pGp documentation about that it prints hex value")
Signed-off-by: Binbin Zhou <zhoubinbin@loongson.cn>
Reviewed-by: Yanteng Si<siyanteng@loongson.cn>
Reviewed-by: Wu XiangCheng <bobwxc@email.cn>
Link: https://lore.kernel.org/r/2ba15ab2aa46bfdd400d1c043eecc12bc6154836.1655863769.git.zhoubinbin@loongson.cnSigned-off-by: Jonathan Corbet <corbet@lwn.net>

Synchronous translation from upstream commit 7d9e2661
("printk: Move the printk() kerneldoc comment to its new home")
Signed-off-by: Binbin Zhou <zhoubinbin@loongson.cn>
Reviewed-by: Yanteng Si<siyanteng@loongson.cn>
Reviewed-by: Wu XiangCheng <bobwxc@email.cn>
Link: https://lore.kernel.org/r/56c6d212d6835029b4adf19cf78eec49c7a126d6.1655863769.git.zhoubinbin@loongson.cnSigned-off-by: Jonathan Corbet <corbet@lwn.net>

Synchronous translation from the following commits(Latest in front):

[1]: commit 84dacdbd("mm: document and polish read-ahead code")

[2]: commit 2f52578f("mm/util: Add folio_mapping() and
     folio_file_mapping()")

[3]: commit 889a3747("mm/lru: Add folio LRU functions")

[4]: commit c24016ac("mm: Add folio reference count functions")
Signed-off-by: Binbin Zhou <zhoubinbin@loongson.cn>
Reviewed-by: Yanteng Si<siyanteng@loongson.cn>
Reviewed-by: Wu XiangCheng <bobwxc@email.cn>
Link: https://lore.kernel.org/r/0bd7b03a5d38dd1599715343360bef4289b7c0fb.1655863769.git.zhoubinbin@loongson.cnSigned-off-by: Jonathan Corbet <corbet@lwn.net>

Synchronous translation from upstream commit 640d1930
("block: Add bio_for_each_folio_all()")
Signed-off-by: Binbin Zhou <zhoubinbin@loongson.cn>
Reviewed-by: Wu XiangCheng <bobwxc@email.cn>
Reviewed-by: Yanteng Si<siyanteng@loongson.cn>
Link: https://lore.kernel.org/r/9173878562404f4518fecc7c55032fe815f87fd9.1655863769.git.zhoubinbin@loongson.cnSigned-off-by: Jonathan Corbet <corbet@lwn.net>

Synchronous translation from the following commits(Latest in front):

[1]: commit 0953fb26("irq: remove handle_domain_{irq,nmi}()")

[2]: commit 0ddc5e55("Documentation: Fix irq-domain.rst build warning")

[3]: commit 991007ba("Documentation: Update
     irq_domain.rst with new lookup APIs")

[4]: commit 405e94e9("irqdomain: Kill irq_domain_add_legacy_isa")
Signed-off-by: Binbin Zhou <zhoubinbin@loongson.cn>
Reviewed-by: Yanteng Si<siyanteng@loongson.cn>
Reviewed-by: Wu XiangCheng <bobwxc@email.cn>
Link: https://lore.kernel.org/r/eb82606f323c4c25e497a01a060e1e76f18be72f.1655863769.git.zhoubinbin@loongson.cnSigned-off-by: Jonathan Corbet <corbet@lwn.net>

Synchronous translation from upstream commit c9871c80
("Documentation: core-api/cpuhotplug: Rewrite the API section")
Signed-off-by: Binbin Zhou <zhoubinbin@loongson.cn>
Reviewed-by: Yanteng Si<siyanteng@loongson.cn>
Reviewed-by: Wu XiangCheng <bobwxc@email.cn>
Link: https://lore.kernel.org/r/9a123a1938a09f883db0b429396954e0792c84c1.1655863769.git.zhoubinbin@loongson.cnSigned-off-by: Jonathan Corbet <corbet@lwn.net>

Synchronous translation from upstream commit 08b0b005
("mm: Add flush_dcache_folio()")
Signed-off-by: Binbin Zhou <zhoubinbin@loongson.cn>
Reviewed-by: Yanteng Si<siyanteng@loongson.cn>
Reviewed-by: Wu XiangCheng <bobwxc@email.cn>
Link: https://lore.kernel.org/r/d1fe8dfa3cfc3fe38c7caf8b5cf3b3482b5bddf8.1655863769.git.zhoubinbin@loongson.cnSigned-off-by: Jonathan Corbet <corbet@lwn.net>

Correct some simple spelling mistakes in consumer.rst, driver.rst
and using-gpio.rst.
Signed-off-by: Tom Schwindl <schwindl@posteo.de>
Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
Link: https://lore.kernel.org/r/YrTdAv3YPlCiDr2u@posteo.deSigned-off-by: Jonathan Corbet <corbet@lwn.net>

Delete duplicate words of "the".
Signed-off-by: Deming Wang <wangdeming@inspur.com>
Link: https://lore.kernel.org/r/20220624014605.2007-1-wangdeming@inspur.comSigned-off-by: Jonathan Corbet <corbet@lwn.net>

Text in ``literal`` markup must be separated by word separators, so text
like ``lowwater``% renders incorrectly.  Add the suggested "\ " after two
problematic occurrences.
Signed-off-by: Stephen Kitt <steve@sk2.org>
Link: https://lore.kernel.org/r/20220624110230.595740-1-steve@sk2.org
[jc: tweaked to use "\ "]
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

The convention for help text indentation seems to be a single tab followed
by two whitespaces. Do that.

While at it, remove a stray empty line.
Signed-off-by: Juerg Haefliger <juergh@canonical.com>
Link: https://lore.kernel.org/r/20220517140837.331298-1-juergh@canonical.comSigned-off-by: Jonathan Corbet <corbet@lwn.net>

Update zh_CN/admin-guide/reporting-issues.rst to newest English version

commit 247097e2 ("docs: reporting-issues.rst: link new document
                       about regressions")
Signed-off-by: Wu XiangCheng <bobwxc@email.cn>
Reviewed-by: Alex Shi <alexs@kernel.org>
Link: https://lore.kernel.org/r/YoRlDOUl/eg+h/Cc@bobwxc.mipcSigned-off-by: Jonathan Corbet <corbet@lwn.net>

Add a series of blank lines to this document to get consistend rendering as
an RST description list.
Signed-off-by: Martin Liska <mliska@suse.cz>
Link: https://lore.kernel.org/r/d0e576ab-6121-b7d7-da5b-7750f05ca7f4@suse.czSigned-off-by: Jonathan Corbet <corbet@lwn.net>