Potential translation of LKMM docs into ReST

Potential translation of LKMM docs into ReST

[Ignacio Encinas Rubio]

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/

Re: Potential translation of LKMM docs into ReST

[Alan Stern]

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

Re: Potential translation of LKMM docs into ReST

[Mauro Carvalho Chehab]

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

[PATCH] lkmm: docs: Put LKMM documentation into dev-tools book

[Akira Yokosawa]

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

Re: [PATCH] lkmm: docs: Put LKMM documentation into dev-tools book

[Paul E. McKenney]

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
> 
> 

Re: [PATCH] lkmm: docs: Put LKMM documentation into dev-tools book

[Jonathan Corbet]

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

Re: [PATCH] lkmm: docs: Put LKMM documentation into dev-tools book

[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

Re: [PATCH] lkmm: docs: Put LKMM documentation into dev-tools book

[Mauro Carvalho Chehab]

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