Add a document on how to contribute to the documentation
This is mostly a collection of thoughts for how people who want to help out can make the docs better. Hopefully the world will respond with a flurry of useful patches. Acked-by: Jani Nikula <jani.nikula@intel.com> Reviewed-by: Matthew Wilcox (Oracle) <willy@infradead.org> Reviewed-by: Randy Dunlap <rdunlap@infradead.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
This commit is contained in:
Jonathan Corbet
parent
bcac386f3d
commit
d96574b0b4
|
|
@ -0,0 +1,294 @@
|
|||
.. SPDX-License-Identifier: GPL-2.0
|
||||
How to help improve kernel documentation
|
||||
========================================
|
||||
|
||||
Documentation is an important part of any software-development project.
|
||||
Good documentation helps to bring new developers in and helps established
|
||||
developers work more effectively. Without top-quality documentation, a lot
|
||||
of time is wasted in reverse-engineering the code and making avoidable
|
||||
mistakes.
|
||||
|
||||
Unfortunately, the kernel's documentation currently falls far short of what
|
||||
it needs to be to support a project of this size and importance.
|
||||
|
||||
This guide is for contributors who would like to improve that situation.
|
||||
Kernel documentation improvements can be made by developers at a variety of
|
||||
skill levels; they are a relatively easy way to learn the kernel process in
|
||||
general and find a place in the community. The bulk of what follows is the
|
||||
documentation maintainer's list of tasks that most urgently need to be
|
||||
done.
|
||||
|
||||
The documentation TODO list
|
||||
---------------------------
|
||||
|
||||
There is an endless list of tasks that need to be carried out to get our
|
||||
documentation to where it should be. This list contains a number of
|
||||
important items, but is far from exhaustive; if you see a different way to
|
||||
improve the documentation, please do not hold back!
|
||||
|
||||
Addressing warnings
|
||||
~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The documentation build currently spews out an unbelievable number of
|
||||
warnings. When you have that many, you might as well have none at all;
|
||||
people ignore them, and they will never notice when their work adds new
|
||||
ones. For this reason, eliminating warnings is one of the highest-priority
|
||||
tasks on the documentation TODO list. The task itself is reasonably
|
||||
straightforward, but it must be approached in the right way to be
|
||||
successful.
|
||||
|
||||
Warnings issued by a compiler for C code can often be dismissed as false
|
||||
positives, leading to patches aimed at simply shutting the compiler up.
|
||||
Warnings from the documentation build almost always point at a real
|
||||
problem; making those warnings go away requires understanding the problem
|
||||
and fixing it at its source. For this reason, patches fixing documentation
|
||||
warnings should probably not say "fix a warning" in the changelog title;
|
||||
they should indicate the real problem that has been fixed.
|
||||
|
||||
Another important point is that documentation warnings are often created by
|
||||
problems in kerneldoc comments in C code. While the documentation
|
||||
maintainer appreciates being copied on fixes for these warnings, the
|
||||
documentation tree is often not the right one to actually carry those
|
||||
fixes; they should go to the maintainer of the subsystem in question.
|
||||
|
||||
For example, in a documentation build I grabbed a pair of warnings nearly
|
||||
at random::
|
||||
|
||||
./drivers/devfreq/devfreq.c:1818: warning: bad line:
|
||||
- Resource-managed devfreq_register_notifier()
|
||||
./drivers/devfreq/devfreq.c:1854: warning: bad line:
|
||||
- Resource-managed devfreq_unregister_notifier()
|
||||
|
||||
(The lines were split for readability).
|
||||
|
||||
A quick look at the source file named above turned up a couple of kerneldoc
|
||||
comments that look like this::
|
||||
|
||||
/**
|
||||
* devm_devfreq_register_notifier()
|
||||
- Resource-managed devfreq_register_notifier()
|
||||
* @dev: The devfreq user device. (parent of devfreq)
|
||||
* @devfreq: The devfreq object.
|
||||
* @nb: The notifier block to be unregistered.
|
||||
* @list: DEVFREQ_TRANSITION_NOTIFIER.
|
||||
*/
|
||||
|
||||
The problem is the missing "*", which confuses the build system's
|
||||
simplistic idea of what C comment blocks look like. This problem had been
|
||||
present since that comment was added in 2016 — a full four years. Fixing
|
||||
it was a matter of adding the missing asterisks. A quick look at the
|
||||
history for that file showed what the normal format for subject lines is,
|
||||
and ``scripts/get_maintainer.pl`` told me who should receive it. The
|
||||
resulting patch looked like this::
|
||||
|
||||
[PATCH] PM / devfreq: Fix two malformed kerneldoc comments
|
||||
|
||||
Two kerneldoc comments in devfreq.c fail to adhere to the required format,
|
||||
resulting in these doc-build warnings:
|
||||
|
||||
./drivers/devfreq/devfreq.c:1818: warning: bad line:
|
||||
- Resource-managed devfreq_register_notifier()
|
||||
./drivers/devfreq/devfreq.c:1854: warning: bad line:
|
||||
- Resource-managed devfreq_unregister_notifier()
|
||||
|
||||
Add a couple of missing asterisks and make kerneldoc a little happier.
|
||||
|
||||
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
||||
---
|
||||
drivers/devfreq/devfreq.c | 4 ++--
|
||||
1 file changed, 2 insertions(+), 2 deletions(-)
|
||||
|
||||
diff --git a/drivers/devfreq/devfreq.c b/drivers/devfreq/devfreq.c
|
||||
index 57f6944d65a6..00c9b80b3d33 100644
|
||||
--- a/drivers/devfreq/devfreq.c
|
||||
+++ b/drivers/devfreq/devfreq.c
|
||||
@@ -1814,7 +1814,7 @@ static void devm_devfreq_notifier_release(struct device *dev, void *res)
|
||||
|
||||
/**
|
||||
* devm_devfreq_register_notifier()
|
||||
- - Resource-managed devfreq_register_notifier()
|
||||
+ * - Resource-managed devfreq_register_notifier()
|
||||
* @dev: The devfreq user device. (parent of devfreq)
|
||||
* @devfreq: The devfreq object.
|
||||
* @nb: The notifier block to be unregistered.
|
||||
@@ -1850,7 +1850,7 @@ EXPORT_SYMBOL(devm_devfreq_register_notifier);
|
||||
|
||||
/**
|
||||
* devm_devfreq_unregister_notifier()
|
||||
- - Resource-managed devfreq_unregister_notifier()
|
||||
+ * - Resource-managed devfreq_unregister_notifier()
|
||||
* @dev: The devfreq user device. (parent of devfreq)
|
||||
* @devfreq: The devfreq object.
|
||||
* @nb: The notifier block to be unregistered.
|
||||
--
|
||||
2.24.1
|
||||
|
||||
The entire process only took a few minutes. Of course, I then found that
|
||||
somebody else had fixed it in a separate tree, highlighting another lesson:
|
||||
always check linux-next to see if a problem has been fixed before you dig
|
||||
into it.
|
||||
|
||||
Other fixes will take longer, especially those relating to structure
|
||||
members or function parameters that lack documentation. In such cases, it
|
||||
is necessary to work out what the role of those members or parameters is
|
||||
and describe them correctly. Overall, this task gets a little tedious at
|
||||
times, but it's highly important. If we can actually eliminate warnings
|
||||
from the documentation build, then we can start expecting developers to
|
||||
avoid adding new ones.
|
||||
|
||||
Languishing kerneldoc comments
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Developers are encouraged to write kerneldoc comments for their code, but
|
||||
many of those comments are never pulled into the docs build. That makes
|
||||
this information harder to find and, for example, makes Sphinx unable to
|
||||
generate links to that documentation. Adding ``kernel-doc`` directives to
|
||||
the documentation to bring those comments in can help the community derive
|
||||
the full value of the work that has gone into creating them.
|
||||
|
||||
The ``scripts/find-unused-docs.sh`` tool can be used to find these
|
||||
overlooked comments.
|
||||
|
||||
Note that the most value comes from pulling in the documentation for
|
||||
exported functions and data structures. Many subsystems also have
|
||||
kerneldoc comments for internal use; those should not be pulled into the
|
||||
documentation build unless they are placed in a document that is
|
||||
specifically aimed at developers working within the relevant subsystem.
|
||||
|
||||
|
||||
Typo fixes
|
||||
~~~~~~~~~~
|
||||
|
||||
Fixing typographical or formatting errors in the documentation is a quick
|
||||
way to figure out how to create and send patches, and it is a useful
|
||||
service. I am always willing to accept such patches. That said, once you
|
||||
have fixed a few, please consider moving on to more advanced tasks, leaving
|
||||
some typos for the next beginner to address.
|
||||
|
||||
Please note that some things are *not* typos and should not be "fixed":
|
||||
|
||||
- Both American and British English spellings are allowed within the
|
||||
kernel documentation. There is no need to fix one by replacing it with
|
||||
the other.
|
||||
|
||||
- The question of whether a period should be followed by one or two spaces
|
||||
is not to be debated in the context of kernel documentation. Other
|
||||
areas of rational disagreement, such as the "Oxford comma", are also
|
||||
off-topic here.
|
||||
|
||||
As with any patch to any project, please consider whether your change is
|
||||
really making things better.
|
||||
|
||||
Ancient documentation
|
||||
~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Some kernel documentation is current, maintained, and useful. Some
|
||||
documentation is ... not. Dusty, old, and inaccurate documentation can
|
||||
mislead readers and casts doubt on our documentation as a whole. Anything
|
||||
that can be done to address such problems is more than welcome.
|
||||
|
||||
Whenever you are working with a document, please consider whether it is
|
||||
current, whether it needs updating, or whether it should perhaps be removed
|
||||
altogether. There are a number of warning signs that you can pay attention
|
||||
to here:
|
||||
|
||||
- References to 2.x kernels
|
||||
- Pointers to SourceForge repositories
|
||||
- Nothing but typo fixes in the history for several years
|
||||
- Discussion of pre-Git workflows
|
||||
|
||||
The best thing to do, of course, would be to bring the documentation
|
||||
current, adding whatever information is needed. Such work often requires
|
||||
the cooperation of developers familiar with the subsystem in question, of
|
||||
course. Developers are often more than willing to cooperate with people
|
||||
working to improve the documentation when asked nicely, and when their
|
||||
answers are listened to and acted upon.
|
||||
|
||||
Some documentation is beyond hope; we occasionally find documents that
|
||||
refer to code that was removed from the kernel long ago, for example.
|
||||
There is surprising resistance to removing obsolete documentation, but we
|
||||
should do that anyway. Extra cruft in our documentation helps nobody.
|
||||
|
||||
In cases where there is perhaps some useful information in a badly outdated
|
||||
document, and you are unable to update it, the best thing to do may be to
|
||||
add a warning at the beginning. The following text is recommended::
|
||||
|
||||
.. warning ::
|
||||
This document is outdated and in need of attention. Please use
|
||||
this information with caution, and please consider sending patches
|
||||
to update it.
|
||||
|
||||
That way, at least our long-suffering readers have been warned that the
|
||||
document may lead them astray.
|
||||
|
||||
Documentation coherency
|
||||
~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The old-timers around here will remember the Linux books that showed up on
|
||||
the shelves in the 1990s. They were simply collections of documentation
|
||||
files scrounged from various locations on the net. The books have (mostly)
|
||||
improved since then, but the kernel's documentation is still mostly built
|
||||
on that model. It is thousands of files, almost each of which was written
|
||||
in isolation from all of the others. We don't have a coherent body of
|
||||
kernel documentation; we have thousands of individual documents.
|
||||
|
||||
We have been trying to improve the situation through the creation of
|
||||
a set of "books" that group documentation for specific readers. These
|
||||
include:
|
||||
|
||||
- :doc:`../admin-guide/index`
|
||||
- :doc:`../core-api/index`
|
||||
- :doc:`../driver-api/index`
|
||||
- :doc:`../userspace-api/index`
|
||||
|
||||
As well as this book on documentation itself.
|
||||
|
||||
Moving documents into the appropriate books is an important task and needs
|
||||
to continue. There are a couple of challenges associated with this work,
|
||||
though. Moving documentation files creates short-term pain for the people
|
||||
who work with those files; they are understandably unenthusiastic about
|
||||
such changes. Usually the case can be made to move a document once; we
|
||||
really don't want to keep shifting them around, though.
|
||||
|
||||
Even when all documents are in the right place, though, we have only
|
||||
managed to turn a big pile into a group of smaller piles. The work of
|
||||
trying to knit all of those documents together into a single whole has not
|
||||
yet begun. If you have bright ideas on how we could proceed on that front,
|
||||
we would be more than happy to hear them.
|
||||
|
||||
Stylesheet improvements
|
||||
~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
With the adoption of Sphinx we have much nicer-looking HTML output than we
|
||||
once did. But it could still use a lot of improvement; Donald Knuth and
|
||||
Edward Tufte would be unimpressed. That requires tweaking our stylesheets
|
||||
to create more typographically sound, accessible, and readable output.
|
||||
|
||||
Be warned: if you take on this task you are heading into classic bikeshed
|
||||
territory. Expect a lot of opinions and discussion for even relatively
|
||||
obvious changes. That is, alas, the nature of the world we live in.
|
||||
|
||||
Non-LaTeX PDF build
|
||||
~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
This is a decidedly nontrivial task for somebody with a lot of time and
|
||||
Python skills. The Sphinx toolchain is relatively small and well
|
||||
contained; it is easy to add to a development system. But building PDF or
|
||||
EPUB output requires installing LaTeX, which is anything but small or well
|
||||
contained. That would be a nice thing to eliminate.
|
||||
|
||||
The original hope had been to use the rst2pdf tool (https://rst2pdf.org/)
|
||||
for PDF generation, but it turned out to not be up to the task.
|
||||
Development work on rst2pdf seems to have picked up again in recent times,
|
||||
though, which is a hopeful sign. If a suitably motivated developer were to
|
||||
work with that project to make rst2pdf work with the kernel documentation
|
||||
build, the world would be eternally grateful.
|
||||
|
||||
Write more documentation
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Naturally, there are massive parts of the kernel that are severely
|
||||
underdocumented. If you have the knowledge to document a specific kernel
|
||||
subsystem and the desire to do so, please do not hesitate to do some
|
||||
writing and contribute the result to the kernel. Untold numbers of kernel
|
||||
developers and users will thank you.
|
||||
|
|
@ -10,6 +10,7 @@ How to write kernel documentation
|
|||
sphinx
|
||||
kernel-doc
|
||||
parse-headers
|
||||
contributing
|
||||
|
||||
.. only:: subproject and html
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue