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 <[email protected]>
---
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.2
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 <[email protected]> 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
Hi--
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 <[email protected]>
> ---
> 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 <[email protected]> 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 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