The linux kernel documentation

The Linux Kernel documentation¶

This is the top level of the kernel’s documentation tree. Kernel documentation, like the kernel itself, is very much a work in progress; that is especially true as we work to integrate our many scattered 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.

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.

Application-developer documentation¶

The user-space API manual gathers together documents describing aspects of the kernel interface as seen by application developers.

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.

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).

Architecture-specific documentation¶

These books provide programming details about architecture-specific implementation.

Источник

The Linux Kernel documentation¶

This is the top level of the kernel’s documentation tree. Kernel documentation, like the kernel itself, is very much a work in progress; that is especially true as we work to integrate our many scattered 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¶

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.

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.

Application-developer documentation¶

The user-space API manual gathers together documents describing aspects of the kernel interface as seen by application developers.

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.

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).

Architecture-specific documentation¶

These books provide programming details about architecture-specific implementation.

Filesystem Documentation¶

The documentation in this section are provided by specific filesystem subprojects.

Источник

Linux Kernel Documentation¶

Introduction¶

The Linux kernel uses Sphinx to generate pretty documentation from reStructuredText files under Documentation . To build the documentation in HTML or PDF formats, use make htmldocs or make pdfdocs . The generated documentation is placed in Documentation/output .

The reStructuredText files may contain directives to include structured documentation comments, or kernel-doc comments, from source files. Usually these are used to describe the functions and types and design of the code. The kernel-doc comments have some special structure and formatting, but beyond that they are also treated as reStructuredText.

There is also the deprecated DocBook toolchain to generate documentation from DocBook XML template files under Documentation/DocBook . The DocBook files are to be converted to reStructuredText, and the toolchain is slated to be removed.

Finally, there are thousands of plain text documentation files scattered around Documentation . Some of these will likely be converted to reStructuredText over time, but the bulk of them will remain in plain text.

Sphinx Build¶

The usual way to generate the documentation is to run make htmldocs or make pdfdocs . There are also other formats available, see the documentation section of make help . The generated documentation is placed in format-specific subdirectories under Documentation/output .

To generate documentation, Sphinx ( sphinx-build ) must obviously be installed. For prettier HTML output, the Read the Docs Sphinx theme ( sphinx_rtd_theme ) is used if available. For PDF output, rst2pdf is also needed. All of these are widely available and packaged in distributions.

To pass extra options to Sphinx, you can use the SPHINXOPTS make variable. For example, use make SPHINXOPTS=-v htmldocs to get more verbose output.

To remove the generated documentation, run make cleandocs .

Writing Documentation¶

Adding new documentation can be as simple as:

1. Add a new .rst file somewhere under Documentation .
2. Refer to it from the Sphinx main TOC tree in Documentation/index.rst .

This is usually good enough for simple documentation (like the one you’re reading right now), but for larger documents it may be advisable to create a subdirectory (or use an existing one). For example, the graphics subsystem documentation is under Documentation/gpu , split to several .rst files, and has a separate index.rst (with a toctree of its own) referenced from the main index.

See the documentation for Sphinx and reStructuredText on what you can do with them. In particular, the Sphinx reStructuredText Primer is a good place to get started with reStructuredText. There are also some Sphinx specific markup constructs.

Specific guidelines for the kernel documentation¶

Here are some specific guidelines for the kernel documentation:

Please don’t go overboard with reStructuredText markup. Keep it simple.

Please stick to this order of heading adornments:

Источник

The Linux Kernel documentation¶

This is the top level of the kernel’s documentation tree. Kernel documentation, like the kernel itself, is very much a work in progress; that is especially true as we work to integrate our many scattered 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¶

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.

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.

Firmware-related documentation¶

The following holds information on the kernel’s expectations regarding the platform firmwares.

Application-developer documentation¶

The user-space API manual gathers together documents describing aspects of the kernel interface as seen by application developers.

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.

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).

Architecture-agnostic documentation¶

Architecture-specific documentation¶

These books provide programming details about architecture-specific implementation.

Filesystem Documentation¶

The documentation in this section are provided by specific filesystem subprojects.

Источник

The Linux Kernel documentation¶

This is the top level of the kernel’s documentation tree. Kernel documentation, like the kernel itself, is very much a work in progress; that is especially true as we work to integrate our many scattered 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.

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.

Application-developer documentation¶

The user-space API manual gathers together documents describing aspects of the kernel interface as seen by application developers.

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.

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).

Architecture-specific documentation¶

These books provide programming details about architecture-specific implementation.

Источник