* Potential translation of LKMM docs into ReST @ 2025-03-30 11:07 Ignacio Encinas Rubio 2025-03-30 16:09 ` Alan Stern 2025-05-06 2:50 ` [PATCH] lkmm: docs: Put LKMM documentation into dev-tools book Akira Yokosawa 0 siblings, 2 replies; 8+ messages in thread From: Ignacio Encinas Rubio @ 2025-03-30 11:07 UTC (permalink / raw) To: lkmm Cc: mchehab+huawei, paulmck, joel, Akira Yokosawa, linux-kernel-mentees, peterz, stern, corbet, Shuah Khan Hello! There is interest [1] to get the memory model documentation into the built docs. Akira pointed out that this was discussed in the past [2]. A couple of years have gone by, so I was wondering whether the decision to keep plain text documentation still applies. There is an "easy" way [3] to get the plain text documentation into the built docs, but I would be happy to work in a conversion into ReST if that's what you want :) Ccing people involved in [2] Thanks! [1] https://lore.kernel.org/all/87o6y5lvvg.fsf@trenco.lwn.net/ [2] https://lore.kernel.org/lkml/20190901133530.GL4125@linux.ibm.com/ [3] https://lore.kernel.org/all/20220927160559.97154-7-corbet@lwn.net/ ^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: Potential translation of LKMM docs into ReST 2025-03-30 11:07 Potential translation of LKMM docs into ReST Ignacio Encinas Rubio @ 2025-03-30 16:09 ` Alan Stern 2025-03-30 17:52 ` Mauro Carvalho Chehab 2025-05-06 2:50 ` [PATCH] lkmm: docs: Put LKMM documentation into dev-tools book Akira Yokosawa 1 sibling, 1 reply; 8+ messages in thread From: Alan Stern @ 2025-03-30 16:09 UTC (permalink / raw) To: Ignacio Encinas Rubio Cc: lkmm, mchehab+huawei, paulmck, joel, Akira Yokosawa, linux-kernel-mentees, peterz, corbet, Shuah Khan On Sun, Mar 30, 2025 at 01:07:23PM +0200, Ignacio Encinas Rubio wrote: > Hello! > > There is interest [1] to get the memory model documentation into the > built docs. Akira pointed out that this was discussed in the past [2]. > > A couple of years have gone by, so I was wondering whether the decision > to keep plain text documentation still applies. > > There is an "easy" way [3] to get the plain text documentation into the > built docs, but I would be happy to work in a conversion into ReST if > that's what you want :) > > Ccing people involved in [2] > > Thanks! > > [1] https://lore.kernel.org/all/87o6y5lvvg.fsf@trenco.lwn.net/ > [2] https://lore.kernel.org/lkml/20190901133530.GL4125@linux.ibm.com/ > [3] https://lore.kernel.org/all/20220927160559.97154-7-corbet@lwn.net/ I have no great interest in seeing the memory model documentation translated into ReST, but you're welcome to try it and see how it comes out if you want. Some of the files are likely to be easier to convert than others. The only restriction I will insist on is that if the resulting ReST source files end up being unreadable because of all the markup they contain then we must keep the original plain text files too. Alan ^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: Potential translation of LKMM docs into ReST 2025-03-30 16:09 ` Alan Stern @ 2025-03-30 17:52 ` Mauro Carvalho Chehab 0 siblings, 0 replies; 8+ messages in thread From: Mauro Carvalho Chehab @ 2025-03-30 17:52 UTC (permalink / raw) To: Alan Stern Cc: Ignacio Encinas Rubio, lkmm, paulmck, joel, Akira Yokosawa, linux-kernel-mentees, peterz, corbet, Shuah Khan Em Sun, 30 Mar 2025 12:09:22 -0400 Alan Stern <stern@rowland.harvard.edu> escreveu: > On Sun, Mar 30, 2025 at 01:07:23PM +0200, Ignacio Encinas Rubio wrote: > > Hello! > > > > There is interest [1] to get the memory model documentation into the > > built docs. Akira pointed out that this was discussed in the past [2]. > > > > A couple of years have gone by, so I was wondering whether the decision > > to keep plain text documentation still applies. > > > > There is an "easy" way [3] to get the plain text documentation into the > > built docs, but I would be happy to work in a conversion into ReST if > > that's what you want :) > > > > Ccing people involved in [2] > > > > Thanks! > > > > [1] https://lore.kernel.org/all/87o6y5lvvg.fsf@trenco.lwn.net/ > > [2] https://lore.kernel.org/lkml/20190901133530.GL4125@linux.ibm.com/ > > [3] https://lore.kernel.org/all/20220927160559.97154-7-corbet@lwn.net/ > > I have no great interest in seeing the memory model documentation > translated into ReST, but you're welcome to try it and see how it comes > out if you want. Some of the files are likely to be easier to convert > than others. > > The only restriction I will insist on is that if the resulting ReST > source files end up being unreadable because of all the markup they > contain then we must keep the original plain text files too. I did some attempts to convert some of them to ReST. Some files could be a little be tricky if we want them to be converted, but it is possible to go to a minimal set of changes. For instance: Documentation/memory-barriers.txt There is an outdated conversion of it could be found at: https://lkml.org/lkml/2017/5/18/1267 If you take a look on it, most of the changes are minimal. On a quick look on my previous patch, what we have is: 1) the most relevant change: example blocks need to use "::", like: -in 24 different combinations: +in 24 different combinations:: STORE A=3, STORE B=4, y=LOAD A->3, x=LOAD B->4 STORE A=3, STORE B=4, x=LOAD B->4, y=LOAD A->3 2) This won't work: By: foo bar As it will produce a warning and place everything on a single line. The smallest change would be to add a blank line after :, e.g.: By: foo bar 3) This is not valid list on ReST: (*) element (*) element On ReST, unumerated lists use either: - element - element or: * element * element We may also use, instead, a numerated list with: (#) element (#) element On such case, Sphinx will automatically numerate the list This is what I proposed back them to make changes minimal, as i wouldn't need to adjust indentation. 4) Tables in ReST require an extra line before/after it: + =============== ======================= =========================== TYPE MANDATORY SMP CONDITIONAL =============== ======================= =========================== GENERAL mb() smp_mb() WRITE wmb() smp_wmb() READ rmb() smp_rmb() DATA DEPENDENCY read_barrier_depends() smp_read_barrier_depends() + =============== ======================= =========================== 5) Footnotes on ReST require a different notation. Either: [1]_ or: [#]_ and, at the place they're used: .. [1] foo or .. [#] foo 6) Chapter numeration markups need to start from column 1. On files with sub-chapters, some changes to use the same markup might me needed (this is not the case of memory-barriers). The remaining changes I did back then on such patch were cosmetic to make it look more similar to other parts of Documentation, like using "Titles Case" for chapters and converting CONTENTS to a comment for them to not appear at the docs output (as Sphinx already generates a contents index). Regards, Mauro ^ permalink raw reply [flat|nested] 8+ messages in thread
* [PATCH] lkmm: docs: Put LKMM documentation into dev-tools book 2025-03-30 11:07 Potential translation of LKMM docs into ReST Ignacio Encinas Rubio 2025-03-30 16:09 ` Alan Stern @ 2025-05-06 2:50 ` Akira Yokosawa 2025-05-07 0:07 ` Paul E. McKenney 2025-06-09 22:03 ` Jonathan Corbet 1 sibling, 2 replies; 8+ messages in thread From: Akira Yokosawa @ 2025-05-06 2:50 UTC (permalink / raw) To: Paul E. McKenney, Jonathan Corbet Cc: mchehab+huawei, joel, linux-kernel-mentees, peterz, stern, Shuah Khan, Ignacio Encinas Rubio, lkmm, Marco Elver Currently, LKMM docs are not included in any of kernel documentation books. Commit e40573a43d16 ("docs: put atomic*.txt and memory-barriers.txt into the core-api book") covered plain-text docs under Documentation/ by using the "include::" directive along with the ":literal:" option. As LKMM docs are not under Documentation/, the same approach would not work due to the limit of the include:: directive. As a matter of fact, kernel documentation has an extended directive by the name of "kernel-include::", which has no such limitation. Rather than moving LKMM docs around, use the latter with source tree's abspath passed through via the "SOURCEDIR" variable which is now defined in Documentation/Makefile, and make them included in the dev-tools book next to KCSAN. Signed-off-by: Akira Yokosawa <akiyks@gmail.com> Cc: Jonathan Corbet <corbet@lwn.net> --- Hi all, [+CC: Marco, due to the relation of KCSAN and LKMM] Without having seen much interest in "reSTructuring" LKMM docs [1], I went forward in the direction of literally including them without bothering with reST markups. [1]: https://lore.kernel.org/lkmm/837b4d83-b91f-40d1-995a-aa3c5a925b0b@iencinas.com/ This is more of a PoC of minimal glue/wrappers on top of Paul's dev branch which just works for me. [doesn't apply cleanly on top of Jon's docs-next due to a queued change in Documentaion/Makefile] Note that there is *no* change under tools/memory-model/. How does this look to you? Thanks, Akira -- Documentation/Makefile | 1 + Documentation/dev-tools/index.rst | 1 + .../dev-tools/lkmm/docs/access-marking.rst | 11 ++++++++++ .../dev-tools/lkmm/docs/cheatsheet.rst | 11 ++++++++++ .../lkmm/docs/control-dependencies.rst | 11 ++++++++++ .../dev-tools/lkmm/docs/explanation.rst | 11 ++++++++++ .../dev-tools/lkmm/docs/glossary.rst | 11 ++++++++++ .../lkmm/docs/herd-representation.rst | 11 ++++++++++ Documentation/dev-tools/lkmm/docs/index.rst | 21 +++++++++++++++++++ .../dev-tools/lkmm/docs/litmus-tests.rst | 11 ++++++++++ Documentation/dev-tools/lkmm/docs/locking.rst | 11 ++++++++++ .../dev-tools/lkmm/docs/ordering.rst | 11 ++++++++++ Documentation/dev-tools/lkmm/docs/readme.rst | 11 ++++++++++ Documentation/dev-tools/lkmm/docs/recipes.rst | 11 ++++++++++ .../dev-tools/lkmm/docs/references.rst | 11 ++++++++++ Documentation/dev-tools/lkmm/docs/simple.rst | 11 ++++++++++ Documentation/dev-tools/lkmm/index.rst | 15 +++++++++++++ Documentation/dev-tools/lkmm/readme.rst | 11 ++++++++++ MAINTAINERS | 1 + 19 files changed, 193 insertions(+) create mode 100644 Documentation/dev-tools/lkmm/docs/access-marking.rst create mode 100644 Documentation/dev-tools/lkmm/docs/cheatsheet.rst create mode 100644 Documentation/dev-tools/lkmm/docs/control-dependencies.rst create mode 100644 Documentation/dev-tools/lkmm/docs/explanation.rst create mode 100644 Documentation/dev-tools/lkmm/docs/glossary.rst create mode 100644 Documentation/dev-tools/lkmm/docs/herd-representation.rst create mode 100644 Documentation/dev-tools/lkmm/docs/index.rst create mode 100644 Documentation/dev-tools/lkmm/docs/litmus-tests.rst create mode 100644 Documentation/dev-tools/lkmm/docs/locking.rst create mode 100644 Documentation/dev-tools/lkmm/docs/ordering.rst create mode 100644 Documentation/dev-tools/lkmm/docs/readme.rst create mode 100644 Documentation/dev-tools/lkmm/docs/recipes.rst create mode 100644 Documentation/dev-tools/lkmm/docs/references.rst create mode 100644 Documentation/dev-tools/lkmm/docs/simple.rst create mode 100644 Documentation/dev-tools/lkmm/index.rst create mode 100644 Documentation/dev-tools/lkmm/readme.rst diff --git a/Documentation/Makefile b/Documentation/Makefile index 63094646df28..988460db1ce1 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -87,6 +87,7 @@ quiet_cmd_sphinx = SPHINX $@ --> file://$(abspath $(BUILDDIR)/$3/$4) cmd_sphinx = $(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) $(build)=Documentation/userspace-api/media $2 && \ PYTHONDONTWRITEBYTECODE=1 \ BUILDDIR=$(abspath $(BUILDDIR)) SPHINX_CONF=$(abspath $(src)/$5/$(SPHINX_CONF)) \ + SOURCEDIR=$(abspath $(srctree)) \ $(PYTHON3) $(srctree)/scripts/jobserver-exec \ $(CONFIG_SHELL) $(srctree)/Documentation/sphinx/parallel-wrapper.sh \ $(SPHINXBUILD) \ diff --git a/Documentation/dev-tools/index.rst b/Documentation/dev-tools/index.rst index 65c54b27a60b..4b8425e348ab 100644 --- a/Documentation/dev-tools/index.rst +++ b/Documentation/dev-tools/index.rst @@ -29,6 +29,7 @@ Documentation/process/debugging/index.rst ubsan kmemleak kcsan + lkmm/index kfence kselftest kunit/index diff --git a/Documentation/dev-tools/lkmm/docs/access-marking.rst b/Documentation/dev-tools/lkmm/docs/access-marking.rst new file mode 100644 index 000000000000..1c11bb86b8ce --- /dev/null +++ b/Documentation/dev-tools/lkmm/docs/access-marking.rst @@ -0,0 +1,11 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Access Marking +-------------- + +Literal include of ``tools/memory-model/Documentation/access-marking.txt``. + +------------------------------------------------------------------ + +.. kernel-include:: $SOURCEDIR/tools/memory-model/Documentation/access-marking.txt + :literal: diff --git a/Documentation/dev-tools/lkmm/docs/cheatsheet.rst b/Documentation/dev-tools/lkmm/docs/cheatsheet.rst new file mode 100644 index 000000000000..c510a578a8d1 --- /dev/null +++ b/Documentation/dev-tools/lkmm/docs/cheatsheet.rst @@ -0,0 +1,11 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Cheatsheet +---------- + +Literal include of ``tools/memory-model/Documentation/cheatsheet.txt``. + +------------------------------------------------------------------ + +.. kernel-include:: $SOURCEDIR/tools/memory-model/Documentation/cheatsheet.txt + :literal: diff --git a/Documentation/dev-tools/lkmm/docs/control-dependencies.rst b/Documentation/dev-tools/lkmm/docs/control-dependencies.rst new file mode 100644 index 000000000000..db18f18f56f7 --- /dev/null +++ b/Documentation/dev-tools/lkmm/docs/control-dependencies.rst @@ -0,0 +1,11 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Control Dependencies +-------------------- + +Literal include of ``tools/memory-model/Documentation/control-dependencies.txt``. + +------------------------------------------------------------------ + +.. kernel-include:: $SOURCEDIR/tools/memory-model/Documentation/control-dependencies.txt + :literal: diff --git a/Documentation/dev-tools/lkmm/docs/explanation.rst b/Documentation/dev-tools/lkmm/docs/explanation.rst new file mode 100644 index 000000000000..4b4592fb52da --- /dev/null +++ b/Documentation/dev-tools/lkmm/docs/explanation.rst @@ -0,0 +1,11 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Explanation +----------- + +Literal include of ``tools/memory-model/Documentation/explanation.txt``. + +------------------------------------------------------------------ + +.. kernel-include:: $SOURCEDIR/tools/memory-model/Documentation/explanation.txt + :literal: diff --git a/Documentation/dev-tools/lkmm/docs/glossary.rst b/Documentation/dev-tools/lkmm/docs/glossary.rst new file mode 100644 index 000000000000..00376a226675 --- /dev/null +++ b/Documentation/dev-tools/lkmm/docs/glossary.rst @@ -0,0 +1,11 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Glossary +-------- + +Literal include of ``tools/memory-model/Documentation/glossary.txt``. + +------------------------------------------------------------------ + +.. kernel-include:: $SOURCEDIR/tools/memory-model/Documentation/glossary.txt + :literal: diff --git a/Documentation/dev-tools/lkmm/docs/herd-representation.rst b/Documentation/dev-tools/lkmm/docs/herd-representation.rst new file mode 100644 index 000000000000..2fc4e6e5422b --- /dev/null +++ b/Documentation/dev-tools/lkmm/docs/herd-representation.rst @@ -0,0 +1,11 @@ +.. SPDX-License-Identifier: GPL-2.0 + +herd-representation +------------------- + +Literal include of ``tools/memory-model/Documentation/herd-representation``. + +------------------------------------------------------------------ + +.. kernel-include:: $SOURCEDIR/tools/memory-model/Documentation/herd-representation.txt + :literal: diff --git a/Documentation/dev-tools/lkmm/docs/index.rst b/Documentation/dev-tools/lkmm/docs/index.rst new file mode 100644 index 000000000000..abbddcc009de --- /dev/null +++ b/Documentation/dev-tools/lkmm/docs/index.rst @@ -0,0 +1,21 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Documentation +============= + +.. toctree:: + :maxdepth: 1 + + readme + simple + ordering + litmus-tests + locking + recipes + control-dependencies + access-marking + cheatsheet + explanation + herd-representation + glossary + references diff --git a/Documentation/dev-tools/lkmm/docs/litmus-tests.rst b/Documentation/dev-tools/lkmm/docs/litmus-tests.rst new file mode 100644 index 000000000000..f1f27c573189 --- /dev/null +++ b/Documentation/dev-tools/lkmm/docs/litmus-tests.rst @@ -0,0 +1,11 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Litmus Tests +------------ + +Literal include of ``tools/memory-model/Documentation/litmus-tests.txt``. + +------------------------------------------------------------------ + +.. kernel-include:: $SOURCEDIR/tools/memory-model/Documentation/litmus-tests.txt + :literal: diff --git a/Documentation/dev-tools/lkmm/docs/locking.rst b/Documentation/dev-tools/lkmm/docs/locking.rst new file mode 100644 index 000000000000..c396107d2126 --- /dev/null +++ b/Documentation/dev-tools/lkmm/docs/locking.rst @@ -0,0 +1,11 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Locking +------- + +Literal include of ``tools/memory-model/Documentation/locking.txt``. + +------------------------------------------------------------------ + +.. kernel-include:: $SOURCEDIR/tools/memory-model/Documentation/locking.txt + :literal: diff --git a/Documentation/dev-tools/lkmm/docs/ordering.rst b/Documentation/dev-tools/lkmm/docs/ordering.rst new file mode 100644 index 000000000000..aef2f1f8ff89 --- /dev/null +++ b/Documentation/dev-tools/lkmm/docs/ordering.rst @@ -0,0 +1,11 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Ordering +-------- + +Literal include of ``tools/memory-model/Documentation/ordering.txt``. + +------------------------------------------------------------------ + +.. kernel-include:: $SOURCEDIR/tools/memory-model/Documentation/ordering.txt + :literal: diff --git a/Documentation/dev-tools/lkmm/docs/readme.rst b/Documentation/dev-tools/lkmm/docs/readme.rst new file mode 100644 index 000000000000..3353feef52b4 --- /dev/null +++ b/Documentation/dev-tools/lkmm/docs/readme.rst @@ -0,0 +1,11 @@ +.. SPDX-License-Identifier: GPL-2.0 + +README (for LKMM Documentation) +------------------------------- + +Literal include of ``tools/memory-model/Documentation/README``. + +------------------------------------------------------------------ + +.. kernel-include:: $SOURCEDIR/tools/memory-model/Documentation/README + :literal: diff --git a/Documentation/dev-tools/lkmm/docs/recipes.rst b/Documentation/dev-tools/lkmm/docs/recipes.rst new file mode 100644 index 000000000000..a20d114422aa --- /dev/null +++ b/Documentation/dev-tools/lkmm/docs/recipes.rst @@ -0,0 +1,11 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Recipes +------- + +Literal include of ``tools/memory-model/Documentation/recipes.txt``. + +------------------------------------------------------------------ + +.. kernel-include:: $SOURCEDIR/tools/memory-model/Documentation/recipes.txt + :literal: diff --git a/Documentation/dev-tools/lkmm/docs/references.rst b/Documentation/dev-tools/lkmm/docs/references.rst new file mode 100644 index 000000000000..04d3dfe69e3c --- /dev/null +++ b/Documentation/dev-tools/lkmm/docs/references.rst @@ -0,0 +1,11 @@ +.. SPDX-License-Identifier: GPL-2.0 + +References +---------- + +Literal include of ``tools/memory-model/Documentation/references.txt``. + +------------------------------------------------------------------ + +.. kernel-include:: $SOURCEDIR/tools/memory-model/Documentation/references.txt + :literal: diff --git a/Documentation/dev-tools/lkmm/docs/simple.rst b/Documentation/dev-tools/lkmm/docs/simple.rst new file mode 100644 index 000000000000..0372520a43bd --- /dev/null +++ b/Documentation/dev-tools/lkmm/docs/simple.rst @@ -0,0 +1,11 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Simple +------ + +Literal include of ``tools/memory-model/Documentation/simple.txt``. + +------------------------------------------------------------------ + +.. kernel-include:: $SOURCEDIR/tools/memory-model/Documentation/simple.txt + :literal: diff --git a/Documentation/dev-tools/lkmm/index.rst b/Documentation/dev-tools/lkmm/index.rst new file mode 100644 index 000000000000..e52782449ca3 --- /dev/null +++ b/Documentation/dev-tools/lkmm/index.rst @@ -0,0 +1,15 @@ +.. SPDX-License-Identifier: GPL-2.0 + +============================================ +Linux Kernel Memory Consistency Model (LKMM) +============================================ + +This section literally renders documents under ``tools/memory-model/`` +and ``tools/memory-model/Documentation/``, which are maintained in +the *pure* plain text form. + +.. toctree:: + :maxdepth: 2 + + readme + docs/index diff --git a/Documentation/dev-tools/lkmm/readme.rst b/Documentation/dev-tools/lkmm/readme.rst new file mode 100644 index 000000000000..21ddad3b8fe2 --- /dev/null +++ b/Documentation/dev-tools/lkmm/readme.rst @@ -0,0 +1,11 @@ +.. SPDX-License-Identifier: GPL-2.0 + +README (for LKMM) +================= + +Literal include of ``tools/memory-model/README``. + +------------------------------------------------------------ + +.. kernel-include:: $SOURCEDIR/tools/memory-model/README + :literal: diff --git a/MAINTAINERS b/MAINTAINERS index 96b827049501..c95b93e74287 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -13714,6 +13714,7 @@ T: git git://git.kernel.org/pub/scm/linux/kernel/git/rcu/linux.git rcu/dev F: Documentation/atomic_bitops.txt F: Documentation/atomic_t.txt F: Documentation/core-api/refcount-vs-atomic.rst +F: Documentation/dev-tools/lkmm/ F: Documentation/litmus-tests/ F: Documentation/memory-barriers.txt F: tools/memory-model/ base-commit: e245fbc31c2450481e83110583793ea2eb51e7f7 -- 2.43.0 ^ permalink raw reply related [flat|nested] 8+ messages in thread
* Re: [PATCH] lkmm: docs: Put LKMM documentation into dev-tools book 2025-05-06 2:50 ` [PATCH] lkmm: docs: Put LKMM documentation into dev-tools book Akira Yokosawa @ 2025-05-07 0:07 ` Paul E. McKenney 2025-06-09 22:03 ` Jonathan Corbet 1 sibling, 0 replies; 8+ messages in thread From: Paul E. McKenney @ 2025-05-07 0:07 UTC (permalink / raw) To: Akira Yokosawa Cc: Jonathan Corbet, mchehab+huawei, joel, linux-kernel-mentees, peterz, stern, Shuah Khan, Ignacio Encinas Rubio, lkmm, Marco Elver On Tue, May 06, 2025 at 11:50:08AM +0900, Akira Yokosawa wrote: > Currently, LKMM docs are not included in any of kernel documentation > books. > > Commit e40573a43d16 ("docs: put atomic*.txt and memory-barriers.txt > into the core-api book") covered plain-text docs under Documentation/ > by using the "include::" directive along with the ":literal:" option. > > As LKMM docs are not under Documentation/, the same approach would not > work due to the limit of the include:: directive. > > As a matter of fact, kernel documentation has an extended directive > by the name of "kernel-include::", which has no such limitation. > > Rather than moving LKMM docs around, use the latter with source tree's > abspath passed through via the "SOURCEDIR" variable which is now defined > in Documentation/Makefile, and make them included in the dev-tools book > next to KCSAN. > > Signed-off-by: Akira Yokosawa <akiyks@gmail.com> > Cc: Jonathan Corbet <corbet@lwn.net> > --- > Hi all, [+CC: Marco, due to the relation of KCSAN and LKMM] > > Without having seen much interest in "reSTructuring" LKMM docs [1], > I went forward in the direction of literally including them without > bothering with reST markups. > > [1]: https://lore.kernel.org/lkmm/837b4d83-b91f-40d1-995a-aa3c5a925b0b@iencinas.com/ > > This is more of a PoC of minimal glue/wrappers on top of Paul's dev > branch which just works for me. > [doesn't apply cleanly on top of Jon's docs-next due to a queued > change in Documentaion/Makefile] > > Note that there is *no* change under tools/memory-model/. > How does this look to you? Looks fine to me! Thanx, Paul > Thanks, Akira > -- > Documentation/Makefile | 1 + > Documentation/dev-tools/index.rst | 1 + > .../dev-tools/lkmm/docs/access-marking.rst | 11 ++++++++++ > .../dev-tools/lkmm/docs/cheatsheet.rst | 11 ++++++++++ > .../lkmm/docs/control-dependencies.rst | 11 ++++++++++ > .../dev-tools/lkmm/docs/explanation.rst | 11 ++++++++++ > .../dev-tools/lkmm/docs/glossary.rst | 11 ++++++++++ > .../lkmm/docs/herd-representation.rst | 11 ++++++++++ > Documentation/dev-tools/lkmm/docs/index.rst | 21 +++++++++++++++++++ > .../dev-tools/lkmm/docs/litmus-tests.rst | 11 ++++++++++ > Documentation/dev-tools/lkmm/docs/locking.rst | 11 ++++++++++ > .../dev-tools/lkmm/docs/ordering.rst | 11 ++++++++++ > Documentation/dev-tools/lkmm/docs/readme.rst | 11 ++++++++++ > Documentation/dev-tools/lkmm/docs/recipes.rst | 11 ++++++++++ > .../dev-tools/lkmm/docs/references.rst | 11 ++++++++++ > Documentation/dev-tools/lkmm/docs/simple.rst | 11 ++++++++++ > Documentation/dev-tools/lkmm/index.rst | 15 +++++++++++++ > Documentation/dev-tools/lkmm/readme.rst | 11 ++++++++++ > MAINTAINERS | 1 + > 19 files changed, 193 insertions(+) > create mode 100644 Documentation/dev-tools/lkmm/docs/access-marking.rst > create mode 100644 Documentation/dev-tools/lkmm/docs/cheatsheet.rst > create mode 100644 Documentation/dev-tools/lkmm/docs/control-dependencies.rst > create mode 100644 Documentation/dev-tools/lkmm/docs/explanation.rst > create mode 100644 Documentation/dev-tools/lkmm/docs/glossary.rst > create mode 100644 Documentation/dev-tools/lkmm/docs/herd-representation.rst > create mode 100644 Documentation/dev-tools/lkmm/docs/index.rst > create mode 100644 Documentation/dev-tools/lkmm/docs/litmus-tests.rst > create mode 100644 Documentation/dev-tools/lkmm/docs/locking.rst > create mode 100644 Documentation/dev-tools/lkmm/docs/ordering.rst > create mode 100644 Documentation/dev-tools/lkmm/docs/readme.rst > create mode 100644 Documentation/dev-tools/lkmm/docs/recipes.rst > create mode 100644 Documentation/dev-tools/lkmm/docs/references.rst > create mode 100644 Documentation/dev-tools/lkmm/docs/simple.rst > create mode 100644 Documentation/dev-tools/lkmm/index.rst > create mode 100644 Documentation/dev-tools/lkmm/readme.rst > > diff --git a/Documentation/Makefile b/Documentation/Makefile > index 63094646df28..988460db1ce1 100644 > --- a/Documentation/Makefile > +++ b/Documentation/Makefile > @@ -87,6 +87,7 @@ quiet_cmd_sphinx = SPHINX $@ --> file://$(abspath $(BUILDDIR)/$3/$4) > cmd_sphinx = $(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) $(build)=Documentation/userspace-api/media $2 && \ > PYTHONDONTWRITEBYTECODE=1 \ > BUILDDIR=$(abspath $(BUILDDIR)) SPHINX_CONF=$(abspath $(src)/$5/$(SPHINX_CONF)) \ > + SOURCEDIR=$(abspath $(srctree)) \ > $(PYTHON3) $(srctree)/scripts/jobserver-exec \ > $(CONFIG_SHELL) $(srctree)/Documentation/sphinx/parallel-wrapper.sh \ > $(SPHINXBUILD) \ > diff --git a/Documentation/dev-tools/index.rst b/Documentation/dev-tools/index.rst > index 65c54b27a60b..4b8425e348ab 100644 > --- a/Documentation/dev-tools/index.rst > +++ b/Documentation/dev-tools/index.rst > @@ -29,6 +29,7 @@ Documentation/process/debugging/index.rst > ubsan > kmemleak > kcsan > + lkmm/index > kfence > kselftest > kunit/index > diff --git a/Documentation/dev-tools/lkmm/docs/access-marking.rst b/Documentation/dev-tools/lkmm/docs/access-marking.rst > new file mode 100644 > index 000000000000..1c11bb86b8ce > --- /dev/null > +++ b/Documentation/dev-tools/lkmm/docs/access-marking.rst > @@ -0,0 +1,11 @@ > +.. SPDX-License-Identifier: GPL-2.0 > + > +Access Marking > +-------------- > + > +Literal include of ``tools/memory-model/Documentation/access-marking.txt``. > + > +------------------------------------------------------------------ > + > +.. kernel-include:: $SOURCEDIR/tools/memory-model/Documentation/access-marking.txt > + :literal: > diff --git a/Documentation/dev-tools/lkmm/docs/cheatsheet.rst b/Documentation/dev-tools/lkmm/docs/cheatsheet.rst > new file mode 100644 > index 000000000000..c510a578a8d1 > --- /dev/null > +++ b/Documentation/dev-tools/lkmm/docs/cheatsheet.rst > @@ -0,0 +1,11 @@ > +.. SPDX-License-Identifier: GPL-2.0 > + > +Cheatsheet > +---------- > + > +Literal include of ``tools/memory-model/Documentation/cheatsheet.txt``. > + > +------------------------------------------------------------------ > + > +.. kernel-include:: $SOURCEDIR/tools/memory-model/Documentation/cheatsheet.txt > + :literal: > diff --git a/Documentation/dev-tools/lkmm/docs/control-dependencies.rst b/Documentation/dev-tools/lkmm/docs/control-dependencies.rst > new file mode 100644 > index 000000000000..db18f18f56f7 > --- /dev/null > +++ b/Documentation/dev-tools/lkmm/docs/control-dependencies.rst > @@ -0,0 +1,11 @@ > +.. SPDX-License-Identifier: GPL-2.0 > + > +Control Dependencies > +-------------------- > + > +Literal include of ``tools/memory-model/Documentation/control-dependencies.txt``. > + > +------------------------------------------------------------------ > + > +.. kernel-include:: $SOURCEDIR/tools/memory-model/Documentation/control-dependencies.txt > + :literal: > diff --git a/Documentation/dev-tools/lkmm/docs/explanation.rst b/Documentation/dev-tools/lkmm/docs/explanation.rst > new file mode 100644 > index 000000000000..4b4592fb52da > --- /dev/null > +++ b/Documentation/dev-tools/lkmm/docs/explanation.rst > @@ -0,0 +1,11 @@ > +.. SPDX-License-Identifier: GPL-2.0 > + > +Explanation > +----------- > + > +Literal include of ``tools/memory-model/Documentation/explanation.txt``. > + > +------------------------------------------------------------------ > + > +.. kernel-include:: $SOURCEDIR/tools/memory-model/Documentation/explanation.txt > + :literal: > diff --git a/Documentation/dev-tools/lkmm/docs/glossary.rst b/Documentation/dev-tools/lkmm/docs/glossary.rst > new file mode 100644 > index 000000000000..00376a226675 > --- /dev/null > +++ b/Documentation/dev-tools/lkmm/docs/glossary.rst > @@ -0,0 +1,11 @@ > +.. SPDX-License-Identifier: GPL-2.0 > + > +Glossary > +-------- > + > +Literal include of ``tools/memory-model/Documentation/glossary.txt``. > + > +------------------------------------------------------------------ > + > +.. kernel-include:: $SOURCEDIR/tools/memory-model/Documentation/glossary.txt > + :literal: > diff --git a/Documentation/dev-tools/lkmm/docs/herd-representation.rst b/Documentation/dev-tools/lkmm/docs/herd-representation.rst > new file mode 100644 > index 000000000000..2fc4e6e5422b > --- /dev/null > +++ b/Documentation/dev-tools/lkmm/docs/herd-representation.rst > @@ -0,0 +1,11 @@ > +.. SPDX-License-Identifier: GPL-2.0 > + > +herd-representation > +------------------- > + > +Literal include of ``tools/memory-model/Documentation/herd-representation``. > + > +------------------------------------------------------------------ > + > +.. kernel-include:: $SOURCEDIR/tools/memory-model/Documentation/herd-representation.txt > + :literal: > diff --git a/Documentation/dev-tools/lkmm/docs/index.rst b/Documentation/dev-tools/lkmm/docs/index.rst > new file mode 100644 > index 000000000000..abbddcc009de > --- /dev/null > +++ b/Documentation/dev-tools/lkmm/docs/index.rst > @@ -0,0 +1,21 @@ > +.. SPDX-License-Identifier: GPL-2.0 > + > +Documentation > +============= > + > +.. toctree:: > + :maxdepth: 1 > + > + readme > + simple > + ordering > + litmus-tests > + locking > + recipes > + control-dependencies > + access-marking > + cheatsheet > + explanation > + herd-representation > + glossary > + references > diff --git a/Documentation/dev-tools/lkmm/docs/litmus-tests.rst b/Documentation/dev-tools/lkmm/docs/litmus-tests.rst > new file mode 100644 > index 000000000000..f1f27c573189 > --- /dev/null > +++ b/Documentation/dev-tools/lkmm/docs/litmus-tests.rst > @@ -0,0 +1,11 @@ > +.. SPDX-License-Identifier: GPL-2.0 > + > +Litmus Tests > +------------ > + > +Literal include of ``tools/memory-model/Documentation/litmus-tests.txt``. > + > +------------------------------------------------------------------ > + > +.. kernel-include:: $SOURCEDIR/tools/memory-model/Documentation/litmus-tests.txt > + :literal: > diff --git a/Documentation/dev-tools/lkmm/docs/locking.rst b/Documentation/dev-tools/lkmm/docs/locking.rst > new file mode 100644 > index 000000000000..c396107d2126 > --- /dev/null > +++ b/Documentation/dev-tools/lkmm/docs/locking.rst > @@ -0,0 +1,11 @@ > +.. SPDX-License-Identifier: GPL-2.0 > + > +Locking > +------- > + > +Literal include of ``tools/memory-model/Documentation/locking.txt``. > + > +------------------------------------------------------------------ > + > +.. kernel-include:: $SOURCEDIR/tools/memory-model/Documentation/locking.txt > + :literal: > diff --git a/Documentation/dev-tools/lkmm/docs/ordering.rst b/Documentation/dev-tools/lkmm/docs/ordering.rst > new file mode 100644 > index 000000000000..aef2f1f8ff89 > --- /dev/null > +++ b/Documentation/dev-tools/lkmm/docs/ordering.rst > @@ -0,0 +1,11 @@ > +.. SPDX-License-Identifier: GPL-2.0 > + > +Ordering > +-------- > + > +Literal include of ``tools/memory-model/Documentation/ordering.txt``. > + > +------------------------------------------------------------------ > + > +.. kernel-include:: $SOURCEDIR/tools/memory-model/Documentation/ordering.txt > + :literal: > diff --git a/Documentation/dev-tools/lkmm/docs/readme.rst b/Documentation/dev-tools/lkmm/docs/readme.rst > new file mode 100644 > index 000000000000..3353feef52b4 > --- /dev/null > +++ b/Documentation/dev-tools/lkmm/docs/readme.rst > @@ -0,0 +1,11 @@ > +.. SPDX-License-Identifier: GPL-2.0 > + > +README (for LKMM Documentation) > +------------------------------- > + > +Literal include of ``tools/memory-model/Documentation/README``. > + > +------------------------------------------------------------------ > + > +.. kernel-include:: $SOURCEDIR/tools/memory-model/Documentation/README > + :literal: > diff --git a/Documentation/dev-tools/lkmm/docs/recipes.rst b/Documentation/dev-tools/lkmm/docs/recipes.rst > new file mode 100644 > index 000000000000..a20d114422aa > --- /dev/null > +++ b/Documentation/dev-tools/lkmm/docs/recipes.rst > @@ -0,0 +1,11 @@ > +.. SPDX-License-Identifier: GPL-2.0 > + > +Recipes > +------- > + > +Literal include of ``tools/memory-model/Documentation/recipes.txt``. > + > +------------------------------------------------------------------ > + > +.. kernel-include:: $SOURCEDIR/tools/memory-model/Documentation/recipes.txt > + :literal: > diff --git a/Documentation/dev-tools/lkmm/docs/references.rst b/Documentation/dev-tools/lkmm/docs/references.rst > new file mode 100644 > index 000000000000..04d3dfe69e3c > --- /dev/null > +++ b/Documentation/dev-tools/lkmm/docs/references.rst > @@ -0,0 +1,11 @@ > +.. SPDX-License-Identifier: GPL-2.0 > + > +References > +---------- > + > +Literal include of ``tools/memory-model/Documentation/references.txt``. > + > +------------------------------------------------------------------ > + > +.. kernel-include:: $SOURCEDIR/tools/memory-model/Documentation/references.txt > + :literal: > diff --git a/Documentation/dev-tools/lkmm/docs/simple.rst b/Documentation/dev-tools/lkmm/docs/simple.rst > new file mode 100644 > index 000000000000..0372520a43bd > --- /dev/null > +++ b/Documentation/dev-tools/lkmm/docs/simple.rst > @@ -0,0 +1,11 @@ > +.. SPDX-License-Identifier: GPL-2.0 > + > +Simple > +------ > + > +Literal include of ``tools/memory-model/Documentation/simple.txt``. > + > +------------------------------------------------------------------ > + > +.. kernel-include:: $SOURCEDIR/tools/memory-model/Documentation/simple.txt > + :literal: > diff --git a/Documentation/dev-tools/lkmm/index.rst b/Documentation/dev-tools/lkmm/index.rst > new file mode 100644 > index 000000000000..e52782449ca3 > --- /dev/null > +++ b/Documentation/dev-tools/lkmm/index.rst > @@ -0,0 +1,15 @@ > +.. SPDX-License-Identifier: GPL-2.0 > + > +============================================ > +Linux Kernel Memory Consistency Model (LKMM) > +============================================ > + > +This section literally renders documents under ``tools/memory-model/`` > +and ``tools/memory-model/Documentation/``, which are maintained in > +the *pure* plain text form. > + > +.. toctree:: > + :maxdepth: 2 > + > + readme > + docs/index > diff --git a/Documentation/dev-tools/lkmm/readme.rst b/Documentation/dev-tools/lkmm/readme.rst > new file mode 100644 > index 000000000000..21ddad3b8fe2 > --- /dev/null > +++ b/Documentation/dev-tools/lkmm/readme.rst > @@ -0,0 +1,11 @@ > +.. SPDX-License-Identifier: GPL-2.0 > + > +README (for LKMM) > +================= > + > +Literal include of ``tools/memory-model/README``. > + > +------------------------------------------------------------ > + > +.. kernel-include:: $SOURCEDIR/tools/memory-model/README > + :literal: > diff --git a/MAINTAINERS b/MAINTAINERS > index 96b827049501..c95b93e74287 100644 > --- a/MAINTAINERS > +++ b/MAINTAINERS > @@ -13714,6 +13714,7 @@ T: git git://git.kernel.org/pub/scm/linux/kernel/git/rcu/linux.git rcu/dev > F: Documentation/atomic_bitops.txt > F: Documentation/atomic_t.txt > F: Documentation/core-api/refcount-vs-atomic.rst > +F: Documentation/dev-tools/lkmm/ > F: Documentation/litmus-tests/ > F: Documentation/memory-barriers.txt > F: tools/memory-model/ > > base-commit: e245fbc31c2450481e83110583793ea2eb51e7f7 > -- > 2.43.0 > > ^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: [PATCH] lkmm: docs: Put LKMM documentation into dev-tools book 2025-05-06 2:50 ` [PATCH] lkmm: docs: Put LKMM documentation into dev-tools book Akira Yokosawa 2025-05-07 0:07 ` Paul E. McKenney @ 2025-06-09 22:03 ` Jonathan Corbet 2025-06-10 2:11 ` Akira Yokosawa 1 sibling, 1 reply; 8+ messages in thread From: Jonathan Corbet @ 2025-06-09 22:03 UTC (permalink / raw) To: Akira Yokosawa, Paul E. McKenney Cc: mchehab+huawei, joel, linux-kernel-mentees, peterz, stern, Shuah Khan, Ignacio Encinas Rubio, lkmm, Marco Elver Akira Yokosawa <akiyks@gmail.com> writes: > Currently, LKMM docs are not included in any of kernel documentation > books. > > Commit e40573a43d16 ("docs: put atomic*.txt and memory-barriers.txt > into the core-api book") covered plain-text docs under Documentation/ > by using the "include::" directive along with the ":literal:" option. > > As LKMM docs are not under Documentation/, the same approach would not > work due to the limit of the include:: directive. > > As a matter of fact, kernel documentation has an extended directive > by the name of "kernel-include::", which has no such limitation. > > Rather than moving LKMM docs around, use the latter with source tree's > abspath passed through via the "SOURCEDIR" variable which is now defined > in Documentation/Makefile, and make them included in the dev-tools book > next to KCSAN. So this fell through the cracks during my May travel, sorry. I've taken a look at it now ... it adds a vast number of build warnings: Documentation/networking/netlink_spec/rt_addr.rst:28: WARNING: duplicate label rt-addr-operation-newaddr, other instance in /stuff/k/git/kernel/Documentation/networking/netlink_spec/rt-addr.rst Documentation/networking/netlink_spec/rt_addr.rst:41: WARNING: duplicate label rt-addr-operation-deladdr, other instance in /stuff/k/git/kernel/Documentation/networking/netlink_spec/rt-addr.rst Documentation/networking/netlink_spec/rt_addr.rst:54: WARNING: duplicate label rt-addr-operation-getaddr, other instance in /stuff/k/git/kernel/Documentation/networking/netlink_spec/rt-addr.rst [...] I haven't had a chance to figure out *why* it would have this particular bizarre effect... jon ^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: [PATCH] lkmm: docs: Put LKMM documentation into dev-tools book 2025-06-09 22:03 ` Jonathan Corbet @ 2025-06-10 2:11 ` Akira Yokosawa 2025-06-10 8:13 ` Mauro Carvalho Chehab 0 siblings, 1 reply; 8+ messages in thread From: Akira Yokosawa @ 2025-06-10 2:11 UTC (permalink / raw) To: Jonathan Corbet, Paul E. McKenney Cc: mchehab+huawei, joel, linux-kernel-mentees, peterz, stern, Shuah Khan, Ignacio Encinas Rubio, lkmm, Marco Elver, Akira Yokosawa On Mon, 09 Jun 2025 16:03:32 -0600, Jonathan Corbet wrote: > Akira Yokosawa <akiyks@gmail.com> writes: > >> Currently, LKMM docs are not included in any of kernel documentation >> books. >> >> Commit e40573a43d16 ("docs: put atomic*.txt and memory-barriers.txt >> into the core-api book") covered plain-text docs under Documentation/ >> by using the "include::" directive along with the ":literal:" option. >> >> As LKMM docs are not under Documentation/, the same approach would not >> work due to the limit of the include:: directive. >> >> As a matter of fact, kernel documentation has an extended directive >> by the name of "kernel-include::", which has no such limitation. >> >> Rather than moving LKMM docs around, use the latter with source tree's >> abspath passed through via the "SOURCEDIR" variable which is now defined >> in Documentation/Makefile, and make them included in the dev-tools book >> next to KCSAN. > > So this fell through the cracks during my May travel, sorry. Thank you for taking the time! > > I've taken a look at it now ... it adds a vast number of build warnings: > > Documentation/networking/netlink_spec/rt_addr.rst:28: WARNING: duplicate label rt-addr-operation-newaddr, other instance in /stuff/k/git/kernel/Documentation/networking/netlink_spec/rt-addr.rst > Documentation/networking/netlink_spec/rt_addr.rst:41: WARNING: duplicate label rt-addr-operation-deladdr, other instance in /stuff/k/git/kernel/Documentation/networking/netlink_spec/rt-addr.rst > Documentation/networking/netlink_spec/rt_addr.rst:54: WARNING: duplicate label rt-addr-operation-getaddr, other instance in /stuff/k/git/kernel/Documentation/networking/netlink_spec/rt-addr.rst > [...] > > I haven't had a chance to figure out *why* it would have this particular > bizarre effect... I don't think those new warnings have anything to do with this patch. This is mentioned by Paolo at: https://lore.kernel.org/495e43ef-ae20-4dda-97c0-cb8ebe97394b@redhat.com/ My understanding is that this rename triggers rebuild of the related doc, which in turns leads to quite a large number of htmldoc warning, but it's really unharmful/pre-existing issue. , and Donald said in his reply at: https://lore.kernel.org/CAD4GDZw+Enkd2dA8f7pNxMadwURFd_tHv1sUwkXqFqxsOquHQQ@mail.gmail.com/ Yes, Documentation/Makefile goes the extra mile to only try deleting a list of .rst files generated from the list of source .yaml files. It would be easier to just delete Documentation/networking/netlink_spec/*.rst which would be able to clean up old generated files in situations like this. HTH. BTW, I assumed Paul would take this patch into his lkmm branch for v6.17, once all is clear for the new uses of "..kernel-include::" with ":literal:". Thanks, Akira ^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: [PATCH] lkmm: docs: Put LKMM documentation into dev-tools book 2025-06-10 2:11 ` Akira Yokosawa @ 2025-06-10 8:13 ` Mauro Carvalho Chehab 0 siblings, 0 replies; 8+ messages in thread From: Mauro Carvalho Chehab @ 2025-06-10 8:13 UTC (permalink / raw) To: Akira Yokosawa Cc: Jonathan Corbet, Paul E. McKenney, joel, linux-kernel-mentees, peterz, stern, Shuah Khan, Ignacio Encinas Rubio, lkmm, Marco Elver, Breno Leitao Em Tue, 10 Jun 2025 11:11:50 +0900 Akira Yokosawa <akiyks@gmail.com> escreveu: > On Mon, 09 Jun 2025 16:03:32 -0600, Jonathan Corbet wrote: > > Akira Yokosawa <akiyks@gmail.com> writes: > > > >> Currently, LKMM docs are not included in any of kernel documentation > >> books. > >> > >> Commit e40573a43d16 ("docs: put atomic*.txt and memory-barriers.txt > >> into the core-api book") covered plain-text docs under Documentation/ > >> by using the "include::" directive along with the ":literal:" option. > >> > >> As LKMM docs are not under Documentation/, the same approach would not > >> work due to the limit of the include:: directive. > >> > >> As a matter of fact, kernel documentation has an extended directive > >> by the name of "kernel-include::", which has no such limitation. > >> > >> Rather than moving LKMM docs around, use the latter with source tree's > >> abspath passed through via the "SOURCEDIR" variable which is now defined > >> in Documentation/Makefile, and make them included in the dev-tools book > >> next to KCSAN. > > > > So this fell through the cracks during my May travel, sorry. > > Thank you for taking the time! > > > > > I've taken a look at it now ... it adds a vast number of build warnings: > > > > Documentation/networking/netlink_spec/rt_addr.rst:28: WARNING: duplicate label rt-addr-operation-newaddr, other instance in /stuff/k/git/kernel/Documentation/networking/netlink_spec/rt-addr.rst > > Documentation/networking/netlink_spec/rt_addr.rst:41: WARNING: duplicate label rt-addr-operation-deladdr, other instance in /stuff/k/git/kernel/Documentation/networking/netlink_spec/rt-addr.rst > > Documentation/networking/netlink_spec/rt_addr.rst:54: WARNING: duplicate label rt-addr-operation-getaddr, other instance in /stuff/k/git/kernel/Documentation/networking/netlink_spec/rt-addr.rst > > [...] > > > > I haven't had a chance to figure out *why* it would have this particular > > bizarre effect... > > I don't think those new warnings have anything to do with this patch. > > This is mentioned by Paolo at: > https://lore.kernel.org/495e43ef-ae20-4dda-97c0-cb8ebe97394b@redhat.com/ > > My understanding is that this rename triggers rebuild of the related > doc, which in turns leads to quite a large number of htmldoc warning, > but it's really unharmful/pre-existing issue. > > , and Donald said in his reply at: > https://lore.kernel.org/CAD4GDZw+Enkd2dA8f7pNxMadwURFd_tHv1sUwkXqFqxsOquHQQ@mail.gmail.com/ > > Yes, Documentation/Makefile goes the extra mile to only try deleting a > list of .rst files generated from the list of source .yaml files. It > would be easier to just delete > Documentation/networking/netlink_spec/*.rst which would be able to > clean up old generated files in situations like this. > > HTH. > > BTW, I assumed Paul would take this patch into his lkmm branch for v6.17, > once all is clear for the new uses of "..kernel-include::" with ":literal:". IMO, that happens because of the extra step introduced by ynl_gen_rst.py. Any file renames and deletes will cause troubles. Btw, with those: YNL_INDEX:=$(srctree)/Documentation/networking/netlink_spec/index.rst YNL_RST_DIR:=$(srctree)/Documentation/networking/netlink_spec YNL_YAML_DIR:=$(srctree)/Documentation/netlink/specs YNL_TOOL:=$(srctree)/tools/net/ynl/pyynl/ynl_gen_rst.py YNL_RST_FILES_TMP := $(patsubst %.yaml,%.rst,$(wildcard $(YNL_YAML_DIR)/*.yaml)) YNL_RST_FILES := $(patsubst $(YNL_YAML_DIR)%,$(YNL_RST_DIR)%, $(YNL_RST_FILES_TMP)) $(YNL_INDEX): $(YNL_RST_FILES) $(Q)$(YNL_TOOL) -o $@ -x $(YNL_RST_DIR)/%.rst: $(YNL_YAML_DIR)/%.yaml $(YNL_TOOL) $(Q)$(YNL_TOOL) -i $< -o $@ the produced ReST files aren't placed inside Documentation/output. They're placed instead at $(srctree). This can be problematic, specially when O= is in place. IMO, the right solution would be to write a Sphinx extension that would be internally calling ynl_gen_rst.py. This way, there won't be a need to store. There is a second option: do something similar to what we did when media uAPI documents got migrated to Sphinx(*). The Makefile part is at: Documentation/userspace-api/media/Makefile Where generated ReST files are stored under $(BUILDDIR). We did this before we start writing our own Sphinx extensions. While such approach works,IMO a Sphinx extension would be better integrated. --- (*) the tool there ensures that the entire uAPI headers will be included on media documentation in a way that all symbols will have a cross-reference to uAPI documentation. This way, if one adds a new uAPI without touching docs, warnings will be generated. > > Thanks, > Akira Thanks, Mauro ^ permalink raw reply [flat|nested] 8+ messages in thread
end of thread, other threads:[~2025-06-10 8:13 UTC | newest] Thread overview: 8+ messages (download: mbox.gz follow: Atom feed -- links below jump to the message on this page -- 2025-03-30 11:07 Potential translation of LKMM docs into ReST Ignacio Encinas Rubio 2025-03-30 16:09 ` Alan Stern 2025-03-30 17:52 ` Mauro Carvalho Chehab 2025-05-06 2:50 ` [PATCH] lkmm: docs: Put LKMM documentation into dev-tools book Akira Yokosawa 2025-05-07 0:07 ` Paul E. McKenney 2025-06-09 22:03 ` Jonathan Corbet 2025-06-10 2:11 ` Akira Yokosawa 2025-06-10 8:13 ` Mauro Carvalho Chehab
This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox