These files describe part of the core API, but have never been converted to
RST due to ... let's say local oppposition. So, create a set of
special-purpose wrappers to ..include these files into a separate page so
that they can be a part of the htmldocs build. Then link them into the
core-api manual and remove them from the "staging" dumping ground.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
---
Documentation/core-api/index.rst | 3 ++
.../core-api/wrappers/atomic_bitops.rst | 18 ++++++++
Documentation/core-api/wrappers/atomic_t.rst | 19 +++++++++
.../core-api/wrappers/memory-barriers.rst | 18 ++++++++
Documentation/staging/index.rst | 42 -------------------
5 files changed, 58 insertions(+), 42 deletions(-)
create mode 100644 Documentation/core-api/wrappers/atomic_bitops.rst
create mode 100644 Documentation/core-api/wrappers/atomic_t.rst
create mode 100644 Documentation/core-api/wrappers/memory-barriers.rst
diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst
index f5d8e3779fe8..b0e7b4771fff 100644
--- a/Documentation/core-api/index.rst
+++ b/Documentation/core-api/index.rst
@@ -45,6 +45,8 @@ Library functionality that is used throughout the kernel.
this_cpu_ops
timekeeping
errseq
+ wrappers/atomic_t
+ wrappers/atomic_bitops
Low level entry and exit
========================
@@ -68,6 +70,7 @@ Documentation/locking/index.rst for more related documentation.
local_ops
padata
../RCU/index
+ wrappers/memory-barriers.rst
Low-level hardware management
=============================
diff --git a/Documentation/core-api/wrappers/atomic_bitops.rst b/Documentation/core-api/wrappers/atomic_bitops.rst
new file mode 100644
index 000000000000..bf24e4081a8f
--- /dev/null
+++ b/Documentation/core-api/wrappers/atomic_bitops.rst
@@ -0,0 +1,18 @@
+.. SPDX-License-Identifier: GPL-2.0
+ This is a simple wrapper to bring atomic_bitops.txt into the RST world
+ until such a time as that file can be converted directly.
+
+=============
+Atomic bitops
+=============
+
+.. raw:: latex
+
+ \footnotesize
+
+.. include:: ../../atomic_bitops.txt
+ :literal:
+
+.. raw:: latex
+
+ \normalsize
diff --git a/Documentation/core-api/wrappers/atomic_t.rst b/Documentation/core-api/wrappers/atomic_t.rst
new file mode 100644
index 000000000000..ed109a964c77
--- /dev/null
+++ b/Documentation/core-api/wrappers/atomic_t.rst
@@ -0,0 +1,19 @@
+.. SPDX-License-Identifier: GPL-2.0
+ This is a simple wrapper to bring atomic_t.txt into the RST world
+ until such a time as that file can be converted directly.
+
+============
+Atomic types
+============
+
+.. raw:: latex
+
+ \footnotesize
+
+.. include:: ../../atomic_t.txt
+ :literal:
+
+.. raw:: latex
+
+ \normalsize
+
diff --git a/Documentation/core-api/wrappers/memory-barriers.rst b/Documentation/core-api/wrappers/memory-barriers.rst
new file mode 100644
index 000000000000..532460b5e3eb
--- /dev/null
+++ b/Documentation/core-api/wrappers/memory-barriers.rst
@@ -0,0 +1,18 @@
+.. SPDX-License-Identifier: GPL-2.0
+ This is a simple wrapper to bring memory-barriers.txt into the RST world
+ until such a time as that file can be converted directly.
+
+============================
+Linux kernel memory barriers
+============================
+
+.. raw:: latex
+
+ \footnotesize
+
+.. include:: ../../memory-barriers.txt
+ :literal:
+
+.. raw:: latex
+
+ \normalsize
diff --git a/Documentation/staging/index.rst b/Documentation/staging/index.rst
index abd0d18254d2..ded8254bc0d7 100644
--- a/Documentation/staging/index.rst
+++ b/Documentation/staging/index.rst
@@ -14,45 +14,3 @@ Unsorted Documentation
static-keys
tee
xz
-
-Atomic Types
-============
-
-.. raw:: latex
-
- \footnotesize
-
-.. include:: ../atomic_t.txt
- :literal:
-
-.. raw:: latex
-
- \normalsize
-
-Atomic bitops
-=============
-
-.. raw:: latex
-
- \footnotesize
-
-.. include:: ../atomic_bitops.txt
- :literal:
-
-.. raw:: latex
-
- \normalsize
-
-Memory Barriers
-===============
-
-.. raw:: latex
-
- \footnotesize
-
-.. include:: ../memory-barriers.txt
- :literal:
-
-.. raw:: latex
-
- \normalsize
--
2.37.2Hi-- On 9/22/22 13:41, Jonathan Corbet wrote: > These files describe part of the core API, but have never been converted to > RST due to ... let's say local oppposition. So, create a set of > special-purpose wrappers to ..include these files into a separate page so > that they can be a part of the htmldocs build. Then link them into the > core-api manual and remove them from the "staging" dumping ground. > > Signed-off-by: Jonathan Corbet <corbet@lwn.net> > --- > Documentation/core-api/index.rst | 3 ++ > .../core-api/wrappers/atomic_bitops.rst | 18 ++++++++ > Documentation/core-api/wrappers/atomic_t.rst | 19 +++++++++ > .../core-api/wrappers/memory-barriers.rst | 18 ++++++++ > Documentation/staging/index.rst | 42 ------------------- > 5 files changed, 58 insertions(+), 42 deletions(-) > create mode 100644 Documentation/core-api/wrappers/atomic_bitops.rst > create mode 100644 Documentation/core-api/wrappers/atomic_t.rst > create mode 100644 Documentation/core-api/wrappers/memory-barriers.rst When I look at https://static.lwn.net/kerneldoc/, I want to move these 3 from "Other documentation": Atomic Types Atomic bitops Memory Barriers to "Internal API Manuals", then I saw this patch... Maybe I am misunderstanding. Is this patch supposed to move those 3 items from Other or not? thanks. -- ~Randy
Randy Dunlap <rdunlap@infradead.org> writes: > When I look at https://static.lwn.net/kerneldoc/, > I want to move these 3 from "Other documentation": > Atomic Types > Atomic bitops > Memory Barriers > > to "Internal API Manuals", then I saw this patch... > Maybe I am misunderstanding. Is this patch supposed to move those 3 items > from Other or not? *Sigh* I somehow pushed an intermediate build of the web pages to that site. That is fixed now; apologies for the confusion. Thanks for taking a look, jon
On 9/23/22 03:41, Jonathan Corbet wrote: > @@ -0,0 +1,18 @@ > +.. SPDX-License-Identifier: GPL-2.0 > + This is a simple wrapper to bring atomic_bitops.txt into the RST world > + until such a time as that file can be converted directly. > + > +============= > +Atomic bitops > +============= > + > +.. raw:: latex > + > + \footnotesize > + > +.. include:: ../../atomic_bitops.txt > + :literal: > + > +.. raw:: latex > + > + \normalsize Shouldn't warning like "This documentation isn't in RST format and included as literal block" be added? -- An old man doll... just what I always wanted! - Clara
Bagas Sanjaya <bagasdotme@gmail.com> writes: > On 9/23/22 03:41, Jonathan Corbet wrote: >> @@ -0,0 +1,18 @@ >> +.. SPDX-License-Identifier: GPL-2.0 >> + This is a simple wrapper to bring atomic_bitops.txt into the RST world >> + until such a time as that file can be converted directly. >> + >> +============= >> +Atomic bitops >> +============= >> + >> +.. raw:: latex >> + >> + \footnotesize >> + >> +.. include:: ../../atomic_bitops.txt >> + :literal: >> + >> +.. raw:: latex >> + >> + \normalsize > > Shouldn't warning like "This documentation isn't in RST format and included > as literal block" be added? Why? Who needs that information and what will they do with it? Thanks, jon
On 9/23/22 20:39, Jonathan Corbet wrote: >> Shouldn't warning like "This documentation isn't in RST format and included >> as literal block" be added? > > Why? Who needs that information and what will they do with it? At least readers will not be surprised with the anomaly... But anyway, for consistency, I'd like to see these *.txt docs be converted to proper RST. Thanks. -- An old man doll... just what I always wanted! - Clara
On 9/24/22 20:18, Bagas Sanjaya wrote: > On 9/23/22 20:39, Jonathan Corbet wrote: >>> Shouldn't warning like "This documentation isn't in RST format and included >>> as literal block" be added? >> >> Why? Who needs that information and what will they do with it? > > At least readers will not be surprised with the anomaly... > > But anyway, for consistency, I'd like to see these *.txt docs be converted > to proper RST. I'm pretty sure that Jonathan knows that those files' owner(s) want them to remain in txt format. -- ~Randy
On 9/25/22 10:48, Randy Dunlap wrote: > > > On 9/24/22 20:18, Bagas Sanjaya wrote: >> On 9/23/22 20:39, Jonathan Corbet wrote: >>>> Shouldn't warning like "This documentation isn't in RST format and included >>>> as literal block" be added? >>> >>> Why? Who needs that information and what will they do with it? >> >> At least readers will not be surprised with the anomaly... >> >> But anyway, for consistency, I'd like to see these *.txt docs be converted >> to proper RST. > > I'm pretty sure that Jonathan knows that those files' owner(s) want them > to remain in txt format. > OK, thanks! -- An old man doll... just what I always wanted! - Clara
© 2016 - 2026 Red Hat, Inc.