[6/8] Documentation: Create a new folder for all timer internals

  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 <anna-maria@linutronix.de>
---
 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
  

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 <anna-maria@linutronix.de>
> ---
>  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 Dunlap <rdunlap@infradead.org> 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 <anna-maria@linutronix.de>
>> ---
>>  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 <anna-maria@linutronix.de> 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 <corbet@lwn.net> wrote:
> Anna-Maria Behnsen <anna-maria@linutronix.de> 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
  

Jonathan Corbet <corbet@lwn.net> writes:

> Anna-Maria Behnsen <anna-maria@linutronix.de> 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 <jani.nikula@linux.intel.com> writes:

> On Thu, 25 Jan 2024, Jonathan Corbet <corbet@lwn.net> 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 <anna-maria@linutronix.de> 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 <corbet@lwn.net> writes:

> Anna-Maria Behnsen <anna-maria@linutronix.de> 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