The structure of documentation changed. There is 'core-api' where also
timer related documentation belongs to. But the timer related documentation
(doesn't matter whether it is up to date or outdated) is still located in a
separate folder with no relation to core-api.
Create a new folder which is located below core-api and make it the new
place for all timer related documentation. Instead of revisiting all files
below the already existing timer folder right now, add a warning banner to
the top of all those files. When it is ensured the content is up to date,
they can be moved to the final destination.
Signed-off-by: Anna-Maria Behnsen <[email protected]>
---
Documentation/core-api/index.rst | 1 +
Documentation/core-api/timers/index.rst | 22 ++++++++++++++++++++++
Documentation/timers/highres.rst | 5 +++++
Documentation/timers/hpet.rst | 5 +++++
Documentation/timers/hrtimers.rst | 5 +++++
Documentation/timers/index.rst | 5 +++++
Documentation/timers/no_hz.rst | 4 ++++
Documentation/timers/timekeeping.rst | 5 +++++
Documentation/timers/timers-howto.rst | 5 +++++
9 files changed, 57 insertions(+)
create mode 100644 Documentation/core-api/timers/index.rst
diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst
index 7a3a08d81f11..5aac1bdc411e 100644
--- a/Documentation/core-api/index.rst
+++ b/Documentation/core-api/index.rst
@@ -128,6 +128,7 @@ Documents that don't fit elsewhere or which have yet to be categorized.
librs
netlink
+ timers/index
.. only:: subproject and html
diff --git a/Documentation/core-api/timers/index.rst b/Documentation/core-api/timers/index.rst
new file mode 100644
index 000000000000..e0a985fe4f89
--- /dev/null
+++ b/Documentation/core-api/timers/index.rst
@@ -0,0 +1,22 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+======
+Timers
+======
+
+This is all timer core related documentation. It is split into two
+sections. The first will provide all information for people who simply want
+to use timers. The second contains all information which are required by
+developers who want to dive deeper into the concepts and implementation of
+the timer infrastructure.
+
+The documentation should cover all files, which are located below
+kernel/timers/ and also the timer related includes.
+
+Information for Users
+=====================
+
+
+
+Information about concepts and internals
+========================================
diff --git a/Documentation/timers/highres.rst b/Documentation/timers/highres.rst
index bde5eb7e5c9e..14bf4e680b59 100644
--- a/Documentation/timers/highres.rst
+++ b/Documentation/timers/highres.rst
@@ -2,6 +2,11 @@
High resolution timers and dynamic ticks design notes
=====================================================
+.. warning:: Documents in this folder might be outdated, as they haven't
+ been revisited for a longer time. Up to date documentation is
+ located in the core-api documentation:
+ :doc:`../core-api/timers/index`
+
Further information can be found in the paper of the OLS 2006 talk "hrtimers
and beyond". The paper is part of the OLS 2006 Proceedings Volume 1, which can
be found on the OLS website:
diff --git a/Documentation/timers/hpet.rst b/Documentation/timers/hpet.rst
index c9d05d3caaca..1459555048d9 100644
--- a/Documentation/timers/hpet.rst
+++ b/Documentation/timers/hpet.rst
@@ -2,6 +2,11 @@
High Precision Event Timer Driver for Linux
===========================================
+.. warning:: Documents in this folder might be outdated, as they haven't
+ been revisited for a longer time. Up to date documentation is
+ located in the core-api documentation:
+ :doc:`../core-api/timers/index`
+
The High Precision Event Timer (HPET) hardware follows a specification
by Intel and Microsoft, revision 1.
diff --git a/Documentation/timers/hrtimers.rst b/Documentation/timers/hrtimers.rst
index f88ff8bae89c..ce8a7b5c1387 100644
--- a/Documentation/timers/hrtimers.rst
+++ b/Documentation/timers/hrtimers.rst
@@ -2,6 +2,11 @@
hrtimers - subsystem for high-resolution kernel timers
======================================================
+.. warning:: Documents in this folder might be outdated, as they haven't
+ been revisited for a longer time. Up to date documentation is
+ located in the core-api documentation:
+ :doc:`../core-api/timers/index`
+
This patch introduces a new subsystem for high-resolution kernel timers.
One might ask the question: we already have a timer subsystem
diff --git a/Documentation/timers/index.rst b/Documentation/timers/index.rst
index 983f91f8f023..f99b26430a1d 100644
--- a/Documentation/timers/index.rst
+++ b/Documentation/timers/index.rst
@@ -4,6 +4,11 @@
Timers
======
+.. warning:: Documents in this folder might be outdated, as they haven't
+ been revisited for a longer time. Up to date documentation is
+ located in the core-api documentation:
+ :doc:`../core-api/timers/index`
+
.. toctree::
:maxdepth: 1
diff --git a/Documentation/timers/no_hz.rst b/Documentation/timers/no_hz.rst
index f8786be15183..04cb41c53eb7 100644
--- a/Documentation/timers/no_hz.rst
+++ b/Documentation/timers/no_hz.rst
@@ -2,6 +2,10 @@
NO_HZ: Reducing Scheduling-Clock Ticks
======================================
+.. warning:: Documents in this folder might be outdated, as they haven't
+ been revisited for a longer time. Up to date documentation is
+ located in the core-api documentation:
+ :doc:`../core-api/timers/index`
This document describes Kconfig options and boot parameters that can
reduce the number of scheduling-clock interrupts, thereby improving energy
diff --git a/Documentation/timers/timekeeping.rst b/Documentation/timers/timekeeping.rst
index f83e98852e2c..36d02d4fc085 100644
--- a/Documentation/timers/timekeeping.rst
+++ b/Documentation/timers/timekeeping.rst
@@ -2,6 +2,11 @@
Clock sources, Clock events, sched_clock() and delay timers
===========================================================
+.. warning:: Documents in this folder might be outdated, as they haven't
+ been revisited for a longer time. Up to date documentation is
+ located in the core-api documentation:
+ :doc:`../core-api/timers/index`
+
This document tries to briefly explain some basic kernel timekeeping
abstractions. It partly pertains to the drivers usually found in
drivers/clocksource in the kernel tree, but the code may be spread out
diff --git a/Documentation/timers/timers-howto.rst b/Documentation/timers/timers-howto.rst
index 5c169e3d29a8..bdf34453339a 100644
--- a/Documentation/timers/timers-howto.rst
+++ b/Documentation/timers/timers-howto.rst
@@ -2,6 +2,11 @@
delays - Information on the various kernel delay / sleep mechanisms
===================================================================
+.. warning:: Documents in this folder might be outdated, as they haven't
+ been revisited for a longer time. Up to date documentation is
+ located in the core-api documentation:
+ :doc:`../core-api/timers/index`
+
This document seeks to answer the common question: "What is the
RightWay (TM) to insert a delay?"
--
2.39.2
Hi,
On 1/23/24 08:47, Anna-Maria Behnsen wrote:
> The structure of documentation changed. There is 'core-api' where also
> timer related documentation belongs to. But the timer related documentation
> (doesn't matter whether it is up to date or outdated) is still located in a
> separate folder with no relation to core-api.
>
> Create a new folder which is located below core-api and make it the new
> place for all timer related documentation. Instead of revisiting all files
> below the already existing timer folder right now, add a warning banner to
> the top of all those files. When it is ensured the content is up to date,
> they can be moved to the final destination.
>
> Signed-off-by: Anna-Maria Behnsen <[email protected]>
> ---
> Documentation/core-api/index.rst | 1 +
> Documentation/core-api/timers/index.rst | 22 ++++++++++++++++++++++
> Documentation/timers/highres.rst | 5 +++++
> Documentation/timers/hpet.rst | 5 +++++
> Documentation/timers/hrtimers.rst | 5 +++++
> Documentation/timers/index.rst | 5 +++++
> Documentation/timers/no_hz.rst | 4 ++++
> Documentation/timers/timekeeping.rst | 5 +++++
> Documentation/timers/timers-howto.rst | 5 +++++
When can we remove the old, "might be outdated" files?
Do you think that some of their contents might be valuable to someone?
I prefer not to have the old documentation and the new.
> 9 files changed, 57 insertions(+)
> create mode 100644 Documentation/core-api/timers/index.rst
>
Thanks.
--
#Randy
Randy Dunlap <[email protected]> writes:
> Hi,
>
> On 1/23/24 08:47, Anna-Maria Behnsen wrote:
>> The structure of documentation changed. There is 'core-api' where also
>> timer related documentation belongs to. But the timer related documentation
>> (doesn't matter whether it is up to date or outdated) is still located in a
>> separate folder with no relation to core-api.
>>
>> Create a new folder which is located below core-api and make it the new
>> place for all timer related documentation. Instead of revisiting all files
>> below the already existing timer folder right now, add a warning banner to
>> the top of all those files. When it is ensured the content is up to date,
>> they can be moved to the final destination.
>>
>> Signed-off-by: Anna-Maria Behnsen <[email protected]>
>> ---
>> Documentation/core-api/index.rst | 1 +
>> Documentation/core-api/timers/index.rst | 22 ++++++++++++++++++++++
>> Documentation/timers/highres.rst | 5 +++++
>> Documentation/timers/hpet.rst | 5 +++++
>> Documentation/timers/hrtimers.rst | 5 +++++
>> Documentation/timers/index.rst | 5 +++++
>> Documentation/timers/no_hz.rst | 4 ++++
>> Documentation/timers/timekeeping.rst | 5 +++++
>> Documentation/timers/timers-howto.rst | 5 +++++
>
> When can we remove the old, "might be outdated" files?
> Do you think that some of their contents might be valuable to someone?
>
> I prefer not to have the old documentation and the new.
>
This is also nothing I prefere for a final solution. But I got stucked
when I was looking for a way to add the actual documentation because I
wanted to add it into a cleaned-up environment. But I don't have the
possibility at the moment to cleanup the existing timer documentation
right away with all its aspects (content, formatting, referencing,
location below Documentation,... ).
So I had those options:
1. wait until I have time for all this before publishing the new
documentation -> not an option because I don't know when there is
time to do all those things in one go
2. Put the new documentation below the existing one and ignore the rest
silently (maybe someone else will clean it up someday) -> not an
option because it suggests that the new documentation structure is
just ignored
3. Just move the old documentation without revisiting it -> not an
option because there might be outdated information and then it
doesn't has a benefit for the reader
4. Add a warning banner at the existing documentation and prepare
everything to get the timer documentation to the proper place and
create a place for timer documentation below the current structure.
The benefit of 4. for me is, that there is this warning banner at the
top. So this suggests the reader, that this has to be revisited before
relying on it for 100%. This banner might also remind the original
author/technically deep involved developer that this should be
updated.
If there is a better way to go, please let me know!
Thanks,
Anna-Maria
Anna-Maria Behnsen <[email protected]> writes:
> 4. Add a warning banner at the existing documentation and prepare
> everything to get the timer documentation to the proper place and
> create a place for timer documentation below the current structure.
>
> The benefit of 4. for me is, that there is this warning banner at the
> top. So this suggests the reader, that this has to be revisited before
> relying on it for 100%. This banner might also remind the original
> author/technically deep involved developer that this should be
> updated.
The best thing, of course, is to just fix all of the documentation and
make it perfect now :)
Failing that, the banners are fine IMO. They mark possibly obsolete
docs, warning readers, and also just might, in an optimal world, inspire
somebody else to work to improve the situation.
I've thought for a while that we should have a standard warning or two
along these lines, like Wikipedia does, but of course haven't done
anything about it.
jon
On Thu, 25 Jan 2024, Jonathan Corbet <[email protected]> wrote:
> Anna-Maria Behnsen <[email protected]> writes:
>> 4. Add a warning banner at the existing documentation and prepare
>> everything to get the timer documentation to the proper place and
>> create a place for timer documentation below the current structure.
>>
>> The benefit of 4. for me is, that there is this warning banner at the
>> top. So this suggests the reader, that this has to be revisited before
>> relying on it for 100%. This banner might also remind the original
>> author/technically deep involved developer that this should be
>> updated.
>
> The best thing, of course, is to just fix all of the documentation and
> make it perfect now :)
>
> Failing that, the banners are fine IMO. They mark possibly obsolete
> docs, warning readers, and also just might, in an optimal world, inspire
> somebody else to work to improve the situation.
>
> I've thought for a while that we should have a standard warning or two
> along these lines, like Wikipedia does, but of course haven't done
> anything about it.
One approach could be to use the todo extension [1], and use todo
directives instead of warnings. With todo_include_todos config set to
True, you get the banners in the code, but it's more of an invitation
for people to fix them. Maybe. :)
BR,
Jani.
[1] https://www.sphinx-doc.org/en/master/usage/extensions/todo.html
--
Jani Nikula, Intel
Jonathan Corbet <[email protected]> writes:
> Anna-Maria Behnsen <[email protected]> writes:
>> 4. Add a warning banner at the existing documentation and prepare
>> everything to get the timer documentation to the proper place and
>> create a place for timer documentation below the current structure.
>>
>> The benefit of 4. for me is, that there is this warning banner at the
>> top. So this suggests the reader, that this has to be revisited before
>> relying on it for 100%. This banner might also remind the original
>> author/technically deep involved developer that this should be
>> updated.
>
> The best thing, of course, is to just fix all of the documentation and
> make it perfect now :)
>
> Failing that, the banners are fine IMO. They mark possibly obsolete
> docs, warning readers, and also just might, in an optimal world, inspire
> somebody else to work to improve the situation.
I hope the world is optimal at least sometimes :)
> I've thought for a while that we should have a standard warning or two
> along these lines, like Wikipedia does, but of course haven't done
> anything about it.
>
Sure, if we could standardize it, I would definitely prefere it! For me
as a not sphinx/rst/... expert, it would be great if only something like
. might_be_outdated:: <optional additional text>
needs to be added to the code. And then the default lines would appear
together with the optional additional text.
Is this what you have been thinking about?
Thanks,
Anna-Maria
Jani Nikula <[email protected]> writes:
> On Thu, 25 Jan 2024, Jonathan Corbet <[email protected]> wrote:
>>
>> I've thought for a while that we should have a standard warning or two
>> along these lines, like Wikipedia does, but of course haven't done
>> anything about it.
>
> One approach could be to use the todo extension [1], and use todo
> directives instead of warnings. With todo_include_todos config set to
> True, you get the banners in the code, but it's more of an invitation
> for people to fix them. Maybe. :)
>
This might be a bit more positive than the red warning box. But with
this todo extension, the box is simply grey and might be easier to
ignore (I don't know if it is that easy to change the appearance).
Thanks,
Anna-Maria
Anna-Maria Behnsen <[email protected]> writes:
>> I've thought for a while that we should have a standard warning or two
>> along these lines, like Wikipedia does, but of course haven't done
>> anything about it.
>>
>
> Sure, if we could standardize it, I would definitely prefere it! For me
> as a not sphinx/rst/... expert, it would be great if only something like
>
> .. might_be_outdated:: <optional additional text>
>
> needs to be added to the code. And then the default lines would appear
> together with the optional additional text.
>
> Is this what you have been thinking about?
You've already put more thought into it than I have :)
I was just thinking in terms of some relatively standard text. I'd
rather not create an extension just for this, but Jani's idea of using
the todo extension could work, or just a convention like:
.. include crufty-stuff-note.rst
might be good enough and not require an extension at all.
Thanks,
jon
Jonathan Corbet <[email protected]> writes:
> Anna-Maria Behnsen <[email protected]> writes:
>
>>> I've thought for a while that we should have a standard warning or two
>>> along these lines, like Wikipedia does, but of course haven't done
>>> anything about it.
>>>
>>
>> Sure, if we could standardize it, I would definitely prefere it! For me
>> as a not sphinx/rst/... expert, it would be great if only something like
>>
>> .. might_be_outdated:: <optional additional text>
>>
>> needs to be added to the code. And then the default lines would appear
>> together with the optional additional text.
>>
>> Is this what you have been thinking about?
>
> You've already put more thought into it than I have :)
>
> I was just thinking in terms of some relatively standard text. I'd
> rather not create an extension just for this, but Jani's idea of using
> the todo extension could work, or just a convention like:
>
> .. include crufty-stuff-note.rst
>
> might be good enough and not require an extension at all.
Maybe also a combination of both - using the todo extension inside the
include file?
I would integrate it into a v2, but I'm not sure, when I have time to
prepare it.
Thanks,
Anna-Maria