forked from Minki/linux
Merge branch 'fp' into docs-mw
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.
This commit is contained in:
Jonathan Corbet
commit
1404f29258
@ -369,7 +369,8 @@ html_static_path = ['sphinx-static']
|
||||
html_use_smartypants = False
|
||||
|
||||
# Custom sidebar templates, maps document names to template names.
|
||||
#html_sidebars = {}
|
||||
# Note that the RTD theme ignores this.
|
||||
html_sidebars = { '**': ['searchbox.html', 'localtoc.html', 'sourcelink.html']}
|
||||
|
||||
# Additional templates that should be rendered to pages, maps page names to
|
||||
# template names.
|
||||
|
||||
@ -43,10 +43,11 @@ annotated objects like this, tools can be run on them to generate more useful
|
||||
information. In particular, on properly annotated objects, ``objtool`` can be
|
||||
run to check and fix the object if needed. Currently, ``objtool`` can report
|
||||
missing frame pointer setup/destruction in functions. It can also
|
||||
automatically generate annotations for :doc:`ORC unwinder <x86/orc-unwinder>`
|
||||
automatically generate annotations for the ORC unwinder
|
||||
(Documentation/x86/orc-unwinder.rst)
|
||||
for most code. Both of these are especially important to support reliable
|
||||
stack traces which are in turn necessary for :doc:`Kernel live patching
|
||||
<livepatch/livepatch>`.
|
||||
stack traces which are in turn necessary for kernel live patching
|
||||
(Documentation/livepatch/livepatch.rst).
|
||||
|
||||
Caveat and Discussion
|
||||
---------------------
|
||||
@ -23,6 +23,7 @@ it.
|
||||
printk-formats
|
||||
printk-index
|
||||
symbol-namespaces
|
||||
asm-annotations
|
||||
|
||||
Data structures and low-level utilities
|
||||
=======================================
|
||||
@ -44,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
|
||||
========================
|
||||
@ -67,6 +70,7 @@ Documentation/locking/index.rst for more related documentation.
|
||||
local_ops
|
||||
padata
|
||||
../RCU/index
|
||||
wrappers/memory-barriers.rst
|
||||
|
||||
Low-level hardware management
|
||||
=============================
|
||||
|
||||
18
Documentation/core-api/wrappers/atomic_bitops.rst
Normal file
18
Documentation/core-api/wrappers/atomic_bitops.rst
Normal file
@ -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
|
||||
19
Documentation/core-api/wrappers/atomic_t.rst
Normal file
19
Documentation/core-api/wrappers/atomic_t.rst
Normal file
@ -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
|
||||
|
||||
18
Documentation/core-api/wrappers/memory-barriers.rst
Normal file
18
Documentation/core-api/wrappers/memory-barriers.rst
Normal file
@ -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
|
||||
@ -1,11 +1,5 @@
|
||||
.. SPDX-License-Identifier: GPL-2.0
|
||||
|
||||
|
||||
.. The Linux Kernel documentation master file, created by
|
||||
sphinx-quickstart on Fri Feb 12 13:51:46 2016.
|
||||
You can adapt this file completely to your liking, but it should at least
|
||||
contain the root `toctree` directive.
|
||||
|
||||
.. _linux_doc:
|
||||
|
||||
The Linux Kernel documentation
|
||||
@ -18,26 +12,72 @@ 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.
|
||||
The essential guides for interacting with the kernel's development
|
||||
community and getting your work upstream.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
process/development-process
|
||||
process/submitting-patches
|
||||
Code of conduct <process/code-of-conduct>
|
||||
maintainer/index
|
||||
All development-process docs <process/index>
|
||||
|
||||
|
||||
Internal API manuals
|
||||
--------------------
|
||||
|
||||
Manuals for use by developers working to interface with the rest of the
|
||||
kernel.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
core-api/index
|
||||
driver-api/index
|
||||
subsystem-apis
|
||||
Locking in the kernel <locking/index>
|
||||
|
||||
Development tools and processes
|
||||
-------------------------------
|
||||
|
||||
Various other manuals with useful information for all kernel developers.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
process/license-rules
|
||||
doc-guide/index
|
||||
dev-tools/index
|
||||
dev-tools/testing-overview
|
||||
kernel-hacking/index
|
||||
trace/index
|
||||
fault-injection/index
|
||||
livepatch/index
|
||||
|
||||
* :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.
|
||||
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
|
||||
kbuild/index
|
||||
The kernel build system <kbuild/index>
|
||||
admin-guide/reporting-issues.rst
|
||||
User-space tools <tools/index>
|
||||
userspace-api/index
|
||||
|
||||
See also: the `Linux man pages <https://www.kernel.org/doc/man-pages/>`_,
|
||||
which are kept separately from the kernel's own documentation.
|
||||
|
||||
Firmware-related documentation
|
||||
------------------------------
|
||||
@ -45,106 +85,11 @@ The following holds information on the kernel's expectations regarding the
|
||||
platform firmwares.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
:maxdepth: 1
|
||||
|
||||
firmware-guide/index
|
||||
devicetree/index
|
||||
|
||||
Application-developer documentation
|
||||
-----------------------------------
|
||||
|
||||
The user-space API manual gathers together documents describing aspects of
|
||||
the kernel interface as seen by application developers.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
userspace-api/index
|
||||
|
||||
|
||||
Introduction to kernel development
|
||||
----------------------------------
|
||||
|
||||
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.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
process/index
|
||||
dev-tools/index
|
||||
doc-guide/index
|
||||
kernel-hacking/index
|
||||
trace/index
|
||||
maintainer/index
|
||||
fault-injection/index
|
||||
livepatch/index
|
||||
|
||||
|
||||
Kernel API 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).
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
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
|
||||
|
||||
asm-annotations
|
||||
|
||||
Architecture-specific documentation
|
||||
-----------------------------------
|
||||
@ -163,9 +108,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
|
||||
|
||||
|
||||
|
||||
@ -5,6 +5,7 @@
|
||||
|
||||
.. _process_index:
|
||||
|
||||
=============================================
|
||||
Working with the kernel development community
|
||||
=============================================
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
58
Documentation/subsystem-apis.rst
Normal file
58
Documentation/subsystem-apis.rst
Normal file
@ -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
|
||||
@ -3751,7 +3751,7 @@ sub process {
|
||||
if ($realfile =~ /\.S$/ &&
|
||||
$line =~ /^\+\s*(?:[A-Z]+_)?SYM_[A-Z]+_(?:START|END)(?:_[A-Z_]+)?\s*\(\s*\.L/) {
|
||||
WARN("AVOID_L_PREFIX",
|
||||
"Avoid using '.L' prefixed local symbol names for denoting a range of code via 'SYM_*_START/END' annotations; see Documentation/asm-annotations.rst\n" . $herecurr);
|
||||
"Avoid using '.L' prefixed local symbol names for denoting a range of code via 'SYM_*_START/END' annotations; see Documentation/core-api/asm-annotations.rst\n" . $herecurr);
|
||||
}
|
||||
|
||||
# check we are in a valid source file C or perl if not then ignore this hunk
|
||||
|
||||
Loading…
Reference in New Issue
Block a user