The top-level index.rst file is the entry point for the kernel's
documentation, especially for readers of the HTML output. It is currently
a mess containing everything we thought to throw in there. Firefox says it
would require 26 pages of paper to print it. That is not a user-friendly
introduction.
This series aims to improve our documentation entry point with a focus on
rewriting index.rst. The result is, IMO, simpler and more approachable.
For anybody who wants to see the rendered results without building the
docs, have a look at:
https://static.lwn.net/kerneldoc/
This time around I've rendered the pages using the "Read The Docs" theme,
since that's what everybody will get by default. That theme ignores the
directives regarding the left column, so the results are not as good there.
I have a series proposing a default-theme change in the works, but that's a
separate topic.
This is only a beginning; I think this kind of organizational effort has to
be pushed down into the lower layers of the docs tree itself. But one has
to start somewhere.
CHANGES from v2: now with less sloppiness. I've tried to respond to all of
the review comments. scripts/checkpatch.pl has been updated to match the
new location of asm-annotations.rst. There is also now a link to the man
pages in the user-oriented documentation section.
CHANGES from v1: I've tried to address the comments from v1, further
cleaning up the front page. I've added the "reporting issues" and "kernel
testing" documents there, and done a bit of cleanup. There is plenty more
yet to be done.
Jonathan Corbet (7):
docs: promote the title of process/index.rst
docs: Rewrite the front page
docs: reconfigure the HTML left column
docs: remove some index.rst cruft
docs: move asm-annotations.rst into core-api
docs: put atomic*.txt and memory-barriers.txt into the core-api book
docs: add a man-pages link to the front page
Documentation/conf.py | 3 +-
.../{ => core-api}/asm-annotations.rst | 7 +-
Documentation/core-api/index.rst | 4 +
.../core-api/wrappers/atomic_bitops.rst | 18 ++
Documentation/core-api/wrappers/atomic_t.rst | 19 +++
.../core-api/wrappers/memory-barriers.rst | 18 ++
Documentation/index.rst | 156 ++++++------------
Documentation/process/index.rst | 1 +
Documentation/staging/index.rst | 42 -----
Documentation/subsystem-apis.rst | 58 +++++++
scripts/checkpatch.pl | 2 +-
11 files changed, 175 insertions(+), 153 deletions(-)
rename Documentation/{ => core-api}/asm-annotations.rst (97%)
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
create mode 100644 Documentation/subsystem-apis.rst
--
2.37.2
The front page is the entry point to the documentation, especially for
people who read it online. It's a big mess of everything we could think to
toss into it. Rewrite the page with an eye toward simplicity and making it
easy for readers to get going toward what they really want to find.
This is only a beginning, but it makes our docs more approachable than
before.
Acked-by: Jani Nikula <[email protected]>
Reviewed-by: David Vernet <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>
---
Documentation/index.rst | 148 +++++++++++--------------------
Documentation/subsystem-apis.rst | 58 ++++++++++++
2 files changed, 110 insertions(+), 96 deletions(-)
create mode 100644 Documentation/subsystem-apis.rst
diff --git a/Documentation/index.rst b/Documentation/index.rst
index 4737c18c97ff..bc492e79f1be 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -18,131 +18,88 @@ documents into a coherent whole. Please note that improvements to the
documentation are welcome; join the linux-doc list at vger.kernel.org if
you want to help out.
-Licensing documentation
------------------------
+Working with the development community
+--------------------------------------
-The following describes the license of the Linux kernel source code
-(GPLv2), how to properly mark the license of individual files in the source
-tree, as well as links to the full license text.
-
-* :ref:`kernel_licensing`
-
-User-oriented documentation
----------------------------
-
-The following manuals are written for *users* of the kernel — those who are
-trying to get it to work optimally on a given system.
+The essential guides for interacting with the kernel's development
+community and getting your work upstream.
.. toctree::
- :maxdepth: 2
-
- admin-guide/index
- kbuild/index
-
-Firmware-related documentation
-------------------------------
-The following holds information on the kernel's expectations regarding the
-platform firmwares.
+ :maxdepth: 1
-.. toctree::
- :maxdepth: 2
+ process/development-process
+ process/submitting-patches
+ Code of conduct <process/code-of-conduct>
+ maintainer/index
+ All development-process docs <process/index>
- firmware-guide/index
- devicetree/index
-Application-developer documentation
------------------------------------
+Internal API manuals
+--------------------
-The user-space API manual gathers together documents describing aspects of
-the kernel interface as seen by application developers.
+Manuals for use by developers working to interface with the rest of the
+kernel.
.. toctree::
- :maxdepth: 2
-
- userspace-api/index
+ :maxdepth: 1
+ core-api/index
+ driver-api/index
+ subsystem-apis
+ Locking in the kernel <locking/index>
-Introduction to kernel development
-----------------------------------
+Development tools and processes
+-------------------------------
-These manuals contain overall information about how to develop the kernel.
-The kernel community is quite large, with thousands of developers
-contributing over the course of a year. As with any large community,
-knowing how things are done will make the process of getting your changes
-merged much easier.
+Various other manuals with useful information for all kernel developers.
.. toctree::
- :maxdepth: 2
+ :maxdepth: 1
- process/index
- dev-tools/index
+ process/license-rules
doc-guide/index
+ dev-tools/index
+ dev-tools/testing-overview
kernel-hacking/index
trace/index
- maintainer/index
fault-injection/index
livepatch/index
-Kernel API documentation
-------------------------
+User-oriented documentation
+---------------------------
-These books get into the details of how specific kernel subsystems work
-from the point of view of a kernel developer. Much of the information here
-is taken directly from the kernel source, with supplemental material added
-as needed (or at least as we managed to add it — probably *not* all that is
-needed).
+The following manuals are written for *users* of the kernel — those who are
+trying to get it to work optimally on a given system and application
+developers seeking information on the kernel's user-space APIs.
.. toctree::
- :maxdepth: 2
+ :maxdepth: 1
+
+ admin-guide/index
+ The kernel build system <kbuild/index>
+ admin-guide/reporting-issues.rst
+ User-space tools <tools/index>
+ userspace-api/index
+
+
+Firmware-related documentation
+------------------------------
+The following holds information on the kernel's expectations regarding the
+platform firmwares.
+
+.. toctree::
+ :maxdepth: 1
+
+ firmware-guide/index
+ devicetree/index
- driver-api/index
- core-api/index
- locking/index
- accounting/index
- block/index
- cdrom/index
- cpu-freq/index
- fb/index
- fpga/index
- hid/index
- i2c/index
- iio/index
- isdn/index
- infiniband/index
- leds/index
- netlabel/index
- networking/index
- pcmcia/index
- power/index
- target/index
- timers/index
- spi/index
- w1/index
- watchdog/index
- virt/index
- input/index
- hwmon/index
- gpu/index
- security/index
- sound/index
- crypto/index
- filesystems/index
- mm/index
- bpf/index
- usb/index
- PCI/index
- scsi/index
- misc-devices/index
- scheduler/index
- mhi/index
- peci/index
Architecture-agnostic documentation
-----------------------------------
.. toctree::
- :maxdepth: 2
+ :maxdepth: 1
asm-annotations
@@ -163,9 +120,8 @@ of the documentation body, or may require some adjustments and/or conversion
to ReStructured Text format, or are simply too old.
.. toctree::
- :maxdepth: 2
+ :maxdepth: 1
- tools/index
staging/index
diff --git a/Documentation/subsystem-apis.rst b/Documentation/subsystem-apis.rst
new file mode 100644
index 000000000000..af65004a80aa
--- /dev/null
+++ b/Documentation/subsystem-apis.rst
@@ -0,0 +1,58 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+==============================
+Kernel subsystem documentation
+==============================
+
+These books get into the details of how specific kernel subsystems work
+from the point of view of a kernel developer. Much of the information here
+is taken directly from the kernel source, with supplemental material added
+as needed (or at least as we managed to add it — probably *not* all that is
+needed).
+
+**Fixme**: much more organizational work is needed here.
+
+.. toctree::
+ :maxdepth: 1
+
+ driver-api/index
+ core-api/index
+ locking/index
+ accounting/index
+ block/index
+ cdrom/index
+ cpu-freq/index
+ fb/index
+ fpga/index
+ hid/index
+ i2c/index
+ iio/index
+ isdn/index
+ infiniband/index
+ leds/index
+ netlabel/index
+ networking/index
+ pcmcia/index
+ power/index
+ target/index
+ timers/index
+ spi/index
+ w1/index
+ watchdog/index
+ virt/index
+ input/index
+ hwmon/index
+ gpu/index
+ security/index
+ sound/index
+ crypto/index
+ filesystems/index
+ mm/index
+ bpf/index
+ usb/index
+ PCI/index
+ scsi/index
+ misc-devices/index
+ scheduler/index
+ mhi/index
+ peci/index
--
2.37.2
On 9/27/22 09:05, Jonathan Corbet wrote:
> The top-level index.rst file is the entry point for the kernel's
> documentation, especially for readers of the HTML output. It is currently
> a mess containing everything we thought to throw in there. Firefox says it
> would require 26 pages of paper to print it. That is not a user-friendly
> introduction.
>
> This series aims to improve our documentation entry point with a focus on
> rewriting index.rst. The result is, IMO, simpler and more approachable.
> For anybody who wants to see the rendered results without building the
> docs, have a look at:
>
> https://static.lwn.net/kerneldoc/
LGTM. Thanks.
for the series:
Acked-by: Randy Dunlap <[email protected]>
> This time around I've rendered the pages using the "Read The Docs" theme,
> since that's what everybody will get by default. That theme ignores the
> directives regarding the left column, so the results are not as good there.
> I have a series proposing a default-theme change in the works, but that's a
> separate topic.
>
> This is only a beginning; I think this kind of organizational effort has to
> be pushed down into the lower layers of the docs tree itself. But one has
> to start somewhere.
>
> CHANGES from v2: now with less sloppiness. I've tried to respond to all of
> the review comments. scripts/checkpatch.pl has been updated to match the
> new location of asm-annotations.rst. There is also now a link to the man
> pages in the user-oriented documentation section.
>
> CHANGES from v1: I've tried to address the comments from v1, further
> cleaning up the front page. I've added the "reporting issues" and "kernel
> testing" documents there, and done a bit of cleanup. There is plenty more
> yet to be done.
--
~Randy
On 9/27/22 23:05, Jonathan Corbet wrote:
> The front page is the entry point to the documentation, especially for
> people who read it online. It's a big mess of everything we could think to
> toss into it. Rewrite the page with an eye toward simplicity and making it
> easy for readers to get going toward what they really want to find.
>
> This is only a beginning, but it makes our docs more approachable than
> before.
>
> Acked-by: Jani Nikula <[email protected]>
> Reviewed-by: David Vernet <[email protected]>
> Signed-off-by: Jonathan Corbet <[email protected]>
> ---
> Documentation/index.rst | 148 +++++++++++--------------------
> Documentation/subsystem-apis.rst | 58 ++++++++++++
> 2 files changed, 110 insertions(+), 96 deletions(-)
> create mode 100644 Documentation/subsystem-apis.rst
>
> diff --git a/Documentation/index.rst b/Documentation/index.rst
> index 4737c18c97ff..bc492e79f1be 100644
> --- a/Documentation/index.rst
> +++ b/Documentation/index.rst
> @@ -18,131 +18,88 @@ documents into a coherent whole. Please note that improvements to the
> documentation are welcome; join the linux-doc list at vger.kernel.org if
> you want to help out.
>
> -Licensing documentation
> ------------------------
> +Working with the development community
> +--------------------------------------
>
<snipped>...
> -User-oriented documentation
> ----------------------------
> -
> -The following manuals are written for *users* of the kernel — those who are
> -trying to get it to work optimally on a given system.
> +The essential guides for interacting with the kernel's development
> +community and getting your work upstream.
>
<snipped>...
> +User-oriented documentation
> +---------------------------
>
> -These books get into the details of how specific kernel subsystems work
> -from the point of view of a kernel developer. Much of the information here
> -is taken directly from the kernel source, with supplemental material added
> -as needed (or at least as we managed to add it — probably *not* all that is
> -needed).
> +The following manuals are written for *users* of the kernel — those who are
> +trying to get it to work optimally on a given system and application
> +developers seeking information on the kernel's user-space APIs.
>
> .. toctree::
> - :maxdepth: 2
> + :maxdepth: 1
> +
> + admin-guide/index
> + The kernel build system <kbuild/index>
> + admin-guide/reporting-issues.rst
> + User-space tools <tools/index>
> + userspace-api/index
> +
Hi jon,
Why did developer documentations list first before user-oriented ones? I looked
the rendered result as if the former was given more spotlight than the latter.
Thanks.
--
An old man doll... just what I always wanted! - Clara
Jonathan Corbet <[email protected]> writes:
> The top-level index.rst file is the entry point for the kernel's
> documentation, especially for readers of the HTML output. It is currently
> a mess containing everything we thought to throw in there. Firefox says it
> would require 26 pages of paper to print it. That is not a user-friendly
> introduction.
>
> This series aims to improve our documentation entry point with a focus on
> rewriting index.rst. The result is, IMO, simpler and more approachable.
> For anybody who wants to see the rendered results without building the
> docs, have a look at:
>
> https://static.lwn.net/kerneldoc/
So I think I'll go ahead and drop this into docs-next shortly. Thanks
to everybody who has commented.
This, of course, has the potential to create conflicts with other 6.1
work that touches Documentation/index.rst. Amazingly, as far as I can
tell, there is only one linux-next commit touching that file - the
addition of the Rust docs. We'll want to be sure that doesn't get lost
during the merge window. I'll be sure to include a suitable heads-up in
my pull request.
Thanks,
jon
On Thu, Sep 29, 2022 at 09:34:18AM -0600, Jonathan Corbet wrote:
> Jonathan Corbet <[email protected]> writes:
>
> > The top-level index.rst file is the entry point for the kernel's
> > documentation, especially for readers of the HTML output. It is currently
> > a mess containing everything we thought to throw in there. Firefox says it
> > would require 26 pages of paper to print it. That is not a user-friendly
> > introduction.
> >
> > This series aims to improve our documentation entry point with a focus on
> > rewriting index.rst. The result is, IMO, simpler and more approachable.
> > For anybody who wants to see the rendered results without building the
> > docs, have a look at:
> >
> > https://static.lwn.net/kerneldoc/
>
> So I think I'll go ahead and drop this into docs-next shortly. Thanks
> to everybody who has commented.
>
> This, of course, has the potential to create conflicts with other 6.1
> work that touches Documentation/index.rst. Amazingly, as far as I can
> tell, there is only one linux-next commit touching that file - the
> addition of the Rust docs. We'll want to be sure that doesn't get lost
> during the merge window. I'll be sure to include a suitable heads-up in
> my pull request.
I can add a note in my PR of Rust too -- how should I suggest it be
resolved?
--
Kees Cook
Kees Cook <[email protected]> writes:
> On Thu, Sep 29, 2022 at 09:34:18AM -0600, Jonathan Corbet wrote:
>> Jonathan Corbet <[email protected]> writes:
>>
>> > The top-level index.rst file is the entry point for the kernel's
>> > documentation, especially for readers of the HTML output. It is currently
>> > a mess containing everything we thought to throw in there. Firefox says it
>> > would require 26 pages of paper to print it. That is not a user-friendly
>> > introduction.
>> >
>> > This series aims to improve our documentation entry point with a focus on
>> > rewriting index.rst. The result is, IMO, simpler and more approachable.
>> > For anybody who wants to see the rendered results without building the
>> > docs, have a look at:
>> >
>> > https://static.lwn.net/kerneldoc/
>>
>> So I think I'll go ahead and drop this into docs-next shortly. Thanks
>> to everybody who has commented.
>>
>> This, of course, has the potential to create conflicts with other 6.1
>> work that touches Documentation/index.rst. Amazingly, as far as I can
>> tell, there is only one linux-next commit touching that file - the
>> addition of the Rust docs. We'll want to be sure that doesn't get lost
>> during the merge window. I'll be sure to include a suitable heads-up in
>> my pull request.
>
> I can add a note in my PR of Rust too -- how should I suggest it be
> resolved?
The Rust documentation change to Documentation/index.rst is simple
enough:
> diff --git a/Documentation/index.rst b/Documentation/index.rst
> index 4737c18c97ff..00722aa20cd7 100644
> --- a/Documentation/index.rst
> +++ b/Documentation/index.rst
> @@ -82,6 +82,7 @@ merged much easier.
> maintainer/index
> fault-injection/index
> livepatch/index
> + rust/index
The resolution should take the docs-next version of the file, but add
that line after "livepatch/index" in its new location.
Thanks,
jon
On Thu, Sep 29, 2022 at 5:34 PM Jonathan Corbet <[email protected]> wrote:
>
> So I think I'll go ahead and drop this into docs-next shortly. Thanks
> to everybody who has commented.
>
> This, of course, has the potential to create conflicts with other 6.1
> work that touches Documentation/index.rst. Amazingly, as far as I can
> tell, there is only one linux-next commit touching that file - the
> addition of the Rust docs. We'll want to be sure that doesn't get lost
> during the merge window. I'll be sure to include a suitable heads-up in
> my pull request.
Thanks for the Cc -- I had not seen the series yet, but it looks way better!
Cheers,
Miguel
[Sending a copy to the linux-next folks as well in the hope that it
helps when the conflict shows up there.]
Jonathan Corbet <[email protected]> writes:
> Kees Cook <[email protected]> writes:
>
>> On Thu, Sep 29, 2022 at 09:34:18AM -0600, Jonathan Corbet wrote:
>>> Jonathan Corbet <[email protected]> writes:
>>>
>>> > The top-level index.rst file is the entry point for the kernel's
>>> > documentation, especially for readers of the HTML output. It is currently
>>> > a mess containing everything we thought to throw in there. Firefox says it
>>> > would require 26 pages of paper to print it. That is not a user-friendly
>>> > introduction.
>>> >
>>> > This series aims to improve our documentation entry point with a focus on
>>> > rewriting index.rst. The result is, IMO, simpler and more approachable.
>>> > For anybody who wants to see the rendered results without building the
>>> > docs, have a look at:
>>> >
>>> > https://static.lwn.net/kerneldoc/
>>>
>>> So I think I'll go ahead and drop this into docs-next shortly. Thanks
>>> to everybody who has commented.
>>>
>>> This, of course, has the potential to create conflicts with other 6.1
>>> work that touches Documentation/index.rst. Amazingly, as far as I can
>>> tell, there is only one linux-next commit touching that file - the
>>> addition of the Rust docs. We'll want to be sure that doesn't get lost
>>> during the merge window. I'll be sure to include a suitable heads-up in
>>> my pull request.
>>
>> I can add a note in my PR of Rust too -- how should I suggest it be
>> resolved?
>
> The Rust documentation change to Documentation/index.rst is simple
> enough:
>
>> diff --git a/Documentation/index.rst b/Documentation/index.rst
>> index 4737c18c97ff..00722aa20cd7 100644
>> --- a/Documentation/index.rst
>> +++ b/Documentation/index.rst
>> @@ -82,6 +82,7 @@ merged much easier.
>> maintainer/index
>> fault-injection/index
>> livepatch/index
>> + rust/index
>
> The resolution should take the docs-next version of the file, but add
> that line after "livepatch/index" in its new location.
>
> Thanks,
>
> jon