iv/linux
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
bfc8a222d3
linux/Documentation/index.rst

184 lines
3.9 KiB
ReStructuredText
Raw Normal View History

docs: arm: convert docs to ReST and rename to *.rst Converts ARM the text files to ReST, preparing them to be an architecture book. The conversion is actually: - add blank lines and identation in order to identify paragraphs; - fix tables markups; - add some lists markups; - mark literal blocks; - adjust title markups. At its new index.rst, let's add a :orphan: while this is not linked to the main index.rst file, in order to avoid build warnings. Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org> Reviewed-by Corentin Labbe <clabbe.montjoie@gmail.com> # For sun4i-ss
2019-04-14 21:51:10 +03:00
Documentation/sphinx: add basic working Sphinx configuration and build Add basic configuration and makefile to build documentation from any .rst files under Documentation using Sphinx. For starters, there's just the placeholder index.rst. At the top level Makefile, hook Sphinx documentation targets alongside (but independent of) the DocBook toolchain, having both be run on the various 'make *docs' targets. All Sphinx processing is placed into Documentation/Makefile.sphinx. Both that and the Documentation/DocBook/Makefile are now expected to handle all the documentation targets, explicitly ignoring them if they're not relevant for that particular toolchain. The changes to the existing DocBook Makefile are kept minimal. There is graceful handling of missing Sphinx and rst2pdf (which is needed for pdf output) by checking for the tool and python module, respectively, with informative messages to the user. If the Read the Docs theme (sphinx_rtd_theme) is available, use it, but otherwise gracefully fall back to the Sphinx default theme, with an informative message to the user, and slightly less pretty HTML output. Sphinx can now handle htmldocs, pdfdocs (if rst2pdf is available), epubdocs and xmldocs targets. The output documents are written into per output type subdirectories under Documentation/output. Finally, you can pass options to sphinx-build using the SPHINXBUILD make variable. For example, 'make SPHINXOPTS=-v htmldocs' for more verbose output from Sphinx. This is based on the original work by Jonathan Corbet, but he probably wouldn't recognize this as his own anymore. Signed-off-by: Jani Nikula <jani.nikula@intel.com>
2016-05-19 15:14:05 +03:00
.. 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.
doc: add some chapter labels The idea is to make it easier to create references (doc-guide does the same). This will be used, for example but not only, in translations to point to the main document. Signed-off-by: Federico Vaga <federico.vaga@vaga.pv.it> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2018-06-06 01:49:01 +03:00
.. _linux_doc:
Make the main documentation title less Geocities This is probably the lamest patch ever, but then again "Welcome to The Linux Kernel's documentation" is nearly equally lame. Really, we don't need to "Welcome" people to the documentation, just tell them what the site is about. Signed-off-by: Konstantin Ryabitsev <konstantin@linuxfoundation.org> Acked-by: Jani Nikula <jani.nikula@intel.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-06-06 23:50:04 +03:00
The Linux Kernel documentation
==============================
Documentation/sphinx: add basic working Sphinx configuration and build Add basic configuration and makefile to build documentation from any .rst files under Documentation using Sphinx. For starters, there's just the placeholder index.rst. At the top level Makefile, hook Sphinx documentation targets alongside (but independent of) the DocBook toolchain, having both be run on the various 'make *docs' targets. All Sphinx processing is placed into Documentation/Makefile.sphinx. Both that and the Documentation/DocBook/Makefile are now expected to handle all the documentation targets, explicitly ignoring them if they're not relevant for that particular toolchain. The changes to the existing DocBook Makefile are kept minimal. There is graceful handling of missing Sphinx and rst2pdf (which is needed for pdf output) by checking for the tool and python module, respectively, with informative messages to the user. If the Read the Docs theme (sphinx_rtd_theme) is available, use it, but otherwise gracefully fall back to the Sphinx default theme, with an informative message to the user, and slightly less pretty HTML output. Sphinx can now handle htmldocs, pdfdocs (if rst2pdf is available), epubdocs and xmldocs targets. The output documents are written into per output type subdirectories under Documentation/output. Finally, you can pass options to sphinx-build using the SPHINXBUILD make variable. For example, 'make SPHINXOPTS=-v htmldocs' for more verbose output from Sphinx. This is based on the original work by Jonathan Corbet, but he probably wouldn't recognize this as his own anymore. Signed-off-by: Jani Nikula <jani.nikula@intel.com>
2016-05-19 15:14:05 +03:00
docs: Tweak the top-level Sphinx page This will be the initial landing point for readers, so give them a bit of introductory material. Also split the TOC into area-specific chunks to make the whole thing a bit more approachable. Reviewed-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-10-27 00:43:00 +03:00
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.
Documentation: Add license-rules.rst to describe how to properly identify file licenses Add a file to the Documentation directory to describe how file licenses should be described in all kernel files, using the SPDX identifier, as well as where all licenses should be in the kernel source tree for people to refer to (LICENSES/). Thanks to Kate and Greg for review and editing and Jonas for the suggestions concerning the meta tags in the licenses files. Signed-off-by: Thomas Gleixner <tglx@linutronix.de> Reviewed-by: Jonas Oberg <jonas@fsfe.org> Reviewed-by: Jonathan Corbet <corbet@lwn.net> Reviewed-by: Philippe Ombredanne <pombredanne@nexb.com> Reviewed-by: Kate Stewart <kstewart@linuxfoundation.org> Reviewed-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-12-29 01:17:17 +03:00
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.
docs: tidy up TOCs and refs to license-rules.rst The documentation and TOCs are organized in a manner of a tree. Adding a TOC to the root, which refers to a file which is located in a subfolder forms a grid. Those TOCs are a bit confusing and thats why we get additional error messages while building partial documentation:: $ make SPHINXDIRS=process htmldocs ... checking consistency... Documentation/process/license-rules.rst: \ WARNING: document isn't included in any toctree To fix it, the *root-license-TOC* is replaced by a reference and the 'license-roles.txt' is added to the Documentation/process/index.rst TOC. BTW: there was an old licences remark in Documentation/process/howto.rst which is also updated, mentioning SPDX and pointing to the license-rules.rst Signed-off-by: Markus Heiser <markus.heiser@darmarit.de> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2018-08-14 14:43:12 +03:00
* :ref:`kernel_licensing`
Documentation: Add license-rules.rst to describe how to properly identify file licenses Add a file to the Documentation directory to describe how file licenses should be described in all kernel files, using the SPDX identifier, as well as where all licenses should be in the kernel source tree for people to refer to (LICENSES/). Thanks to Kate and Greg for review and editing and Jonas for the suggestions concerning the meta tags in the licenses files. Signed-off-by: Thomas Gleixner <tglx@linutronix.de> Reviewed-by: Jonas Oberg <jonas@fsfe.org> Reviewed-by: Jonathan Corbet <corbet@lwn.net> Reviewed-by: Philippe Ombredanne <pombredanne@nexb.com> Reviewed-by: Kate Stewart <kstewart@linuxfoundation.org> Reviewed-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-12-29 01:17:17 +03:00
docs: Tweak the top-level Sphinx page This will be the initial landing point for readers, so give them a bit of introductory material. Also split the TOC into area-specific chunks to make the whole thing a bit more approachable. Reviewed-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-10-27 00:43:00 +03:00
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.
Documentation/sphinx: add basic working Sphinx configuration and build Add basic configuration and makefile to build documentation from any .rst files under Documentation using Sphinx. For starters, there's just the placeholder index.rst. At the top level Makefile, hook Sphinx documentation targets alongside (but independent of) the DocBook toolchain, having both be run on the various 'make *docs' targets. All Sphinx processing is placed into Documentation/Makefile.sphinx. Both that and the Documentation/DocBook/Makefile are now expected to handle all the documentation targets, explicitly ignoring them if they're not relevant for that particular toolchain. The changes to the existing DocBook Makefile are kept minimal. There is graceful handling of missing Sphinx and rst2pdf (which is needed for pdf output) by checking for the tool and python module, respectively, with informative messages to the user. If the Read the Docs theme (sphinx_rtd_theme) is available, use it, but otherwise gracefully fall back to the Sphinx default theme, with an informative message to the user, and slightly less pretty HTML output. Sphinx can now handle htmldocs, pdfdocs (if rst2pdf is available), epubdocs and xmldocs targets. The output documents are written into per output type subdirectories under Documentation/output. Finally, you can pass options to sphinx-build using the SPHINXBUILD make variable. For example, 'make SPHINXOPTS=-v htmldocs' for more verbose output from Sphinx. This is based on the original work by Jonathan Corbet, but he probably wouldn't recognize this as his own anymore. Signed-off-by: Jani Nikula <jani.nikula@intel.com>
2016-05-19 15:14:05 +03:00
.. toctree::
:maxdepth: 2
docs-rst: create an user's manual book Place README, REPORTING-BUGS, SecurityBugs and kernel-parameters on an user's manual book. As we'll be numbering the user's manual, remove the manual numbering from SecurityBugs. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
2016-09-21 15:51:11 +03:00
admin-guide/index
docs: add some directories to the main documentation index The contents of those directories were orphaned at the documentation body. While those directories could likely be moved to be inside some guide, I'm opting to just adding their indexes to the main one, removing the :orphan: and adding the SPDX header. For the drivers, the rationale is that the documentation contains a mix of Kernelspace, uAPI and admin-guide. So, better to keep them on separate directories, as we've be doing with similar subsystem-specific docs that were not split yet. For the others, well... I'm too lazy to do the move. Also, it seems to make sense to keep at least some of those at the main dir (like kbuild, for example). In any case, a latter patch could do the move. Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org> Acked-by: Bartlomiej Zolnierkiewicz <b.zolnierkie@samsung.com>
2019-06-28 14:36:50 +03:00
kbuild/index
docs: Tweak the top-level Sphinx page This will be the initial landing point for readers, so give them a bit of introductory material. Also split the TOC into area-specific chunks to make the whole thing a bit more approachable. Reviewed-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-10-27 00:43:00 +03:00
Documentation: add Linux ACPI to Sphinx TOC tree Add below index.rst files for ACPI subsystem. More docs will be added later. o admin-guide/acpi/index.rst o driver-api/acpi/index.rst o firmware-guide/index.rst Signed-off-by: Changbin Du <changbin.du@gmail.com> Reviewed-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org> Signed-off-by: Rafael J. Wysocki <rafael.j.wysocki@intel.com>
2019-04-25 18:30:54 +03:00
Firmware-related documentation
------------------------------
The following holds information on the kernel's expectations regarding the
platform firmwares.
.. toctree::
:maxdepth: 2
firmware-guide/index
docs: Create a user-space API guide This is meant to be the place for documentation relevant to application developers. It's empty for the moment, but at least we have a place now! Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-04-02 23:58:01 +03:00
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
docs/vm: add index.rst and link MM documentation to top level index Signed-off-by: Mike Rapoport <rppt@linux.vnet.ibm.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2018-03-21 22:22:48 +03:00
userspace-api/index
docs: ioctl: add it to the uAPI guide While 100% of its contents is userspace, let's keep the dir at the same place, as this is a well-known location. Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
2019-06-18 23:13:24 +03:00
ioctl/index
docs: Create a user-space API guide This is meant to be the place for documentation relevant to application developers. It's empty for the moment, but at least we have a place now! Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-04-02 23:58:01 +03:00
docs: Tweak the top-level Sphinx page This will be the initial landing point for readers, so give them a bit of introductory material. Also split the TOC into area-specific chunks to make the whole thing a bit more approachable. Reviewed-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-10-27 00:43:00 +03:00
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
docs: rename development-process/ to process/ As we'll type this a lot, after adding CodingStyle & friends, let's rename the directory name to a shorter one. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
2016-10-18 14:05:32 +03:00
process/index
doc-rst: make dev-tools folder buildable stand-alone Add minimal conf.py and moved dev-tools/tools.rst to dev-tools/index.rst makes the dev-tools folder buildable stand-alone. To build only this folder run:: make SPHINXDIRS=dev-tools htmldocs make SPHINXDIRS=dev-tools pdfdocs Signed-off-by: Markus Heiser <markus.heiser@darmarit.de> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-10-26 09:23:14 +03:00
dev-tools/index
docs-rst: doc-guide: split the kernel-documentation.rst contents Having the kernel-documentation at the topmost level doesn't allow generating a separate PDF file for it. Also, makes harder to add extra contents. So, place it on a sub-dir. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-11-17 13:32:33 +03:00
doc-guide/index
docs-rst: convert kernel-hacking to ReST Use pandoc to convert documentation to ReST by calling Documentation/sphinx/tmplcvt script. - Manually adjusted to use ..note and ..warning - Minor fixes for it to be parsed without errors - Use **bold** for emphasis. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
2017-05-11 14:03:27 +03:00
kernel-hacking/index
Documentation: add Linux tracing to Sphinx TOC tree This just add a index.rst for trace subsystem. More docs will be added later. Cc: Steven Rostedt <rostedt@goodmis.org> Signed-off-by: Changbin Du <changbin.du@intel.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2018-02-17 08:39:34 +03:00
trace/index
doc: add maintainer book There is currently very little documentation in the kernel on maintainer level tasks. In particular there are no documents on creating pull requests to submit to Linus. Quoting Greg Kroah-Hartman on LKML: Anyway, this actually came up at the kernel summit / maintainer meeting a few weeks ago, in that "how do I make a good pull request to Linus" is something we need to document. Here's what I do, and it seems to work well, so maybe we should turn it into the start of the documentation for how to do it. (quote references: kernel summit, Europe 2017) Create a new kernel documentation book 'how to be a maintainer' (suggested by Jonathan Corbet). Add chapters on 'configuring git' and 'creating a pull request'. Most of the content was written by Linus Torvalds and Greg Kroah-Hartman in discussion on LKML. This is stated at the start of one of the chapters and the original email thread is referenced in 'pull-requests.rst'. Signed-off-by: Tobin C. Harding <me@tobin.cc> Reviewed-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org> Reviewed-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-12-04 02:27:29 +03:00
maintainer/index
docs: add some directories to the main documentation index The contents of those directories were orphaned at the documentation body. While those directories could likely be moved to be inside some guide, I'm opting to just adding their indexes to the main one, removing the :orphan: and adding the SPDX header. For the drivers, the rationale is that the documentation contains a mix of Kernelspace, uAPI and admin-guide. So, better to keep them on separate directories, as we've be doing with similar subsystem-specific docs that were not split yet. For the others, well... I'm too lazy to do the move. Also, it seems to make sense to keep at least some of those at the main dir (like kbuild, for example). In any case, a latter patch could do the move. Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org> Acked-by: Bartlomiej Zolnierkiewicz <b.zolnierkie@samsung.com>
2019-06-28 14:36:50 +03:00
fault-injection/index
livepatch/index
docs: Tweak the top-level Sphinx page This will be the initial landing point for readers, so give them a bit of introductory material. Also split the TOC into area-specific chunks to make the whole thing a bit more approachable. Reviewed-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-10-27 00:43:00 +03:00
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
docs/zh_CN: Add coding-style into docs build system Tested by the command: make htmldocs During the compiling process, zh_CN/coding-style.rst has no errors and warnings generated, the generated html document has been checked. Signed-off-by: Andy Deng <theandy.deng@gmail.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-01-25 07:14:33 +03:00
needed).
docs: Tweak the top-level Sphinx page This will be the initial landing point for readers, so give them a bit of introductory material. Also split the TOC into area-specific chunks to make the whole thing a bit more approachable. Reviewed-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-10-27 00:43:00 +03:00
.. toctree::
:maxdepth: 2
docs: split up the driver book We don't need to keep it as a single large file anymore; split it up so that it is easier to manage and the individual sections can be read directly as plain files. Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-08-20 22:17:32 +03:00
driver-api/index
Documentation/00-index: update for new core-api folder Signed-off-by: Silvio Fricke <silvio.fricke@gmail.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-10-28 11:14:10 +03:00
core-api/index
docs: locking: add it to the main index The locking directory is part of the Kernel API bookset. Add it to the index file. Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
2019-06-28 13:29:15 +03:00
locking/index
docs: add some documentation dirs to the driver-api book Those are subsystem docs, with a mix of kABI and user-faced docs. While they're not split, keep the dirs where they are, adding just a pointer to the main index. Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
2019-06-18 23:16:23 +03:00
accounting/index
block/index
docs: add some directories to the main documentation index The contents of those directories were orphaned at the documentation body. While those directories could likely be moved to be inside some guide, I'm opting to just adding their indexes to the main one, removing the :orphan: and adding the SPDX header. For the drivers, the rationale is that the documentation contains a mix of Kernelspace, uAPI and admin-guide. So, better to keep them on separate directories, as we've be doing with similar subsystem-specific docs that were not split yet. For the others, well... I'm too lazy to do the move. Also, it seems to make sense to keep at least some of those at the main dir (like kbuild, for example). In any case, a latter patch could do the move. Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org> Acked-by: Bartlomiej Zolnierkiewicz <b.zolnierkie@samsung.com>
2019-06-28 14:36:50 +03:00
cdrom/index
ide/index
fb/index
fpga/index
docs: add some documentation dirs to the driver-api book Those are subsystem docs, with a mix of kABI and user-faced docs. While they're not split, keep the dirs where they are, adding just a pointer to the main index. Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
2019-06-18 23:16:23 +03:00
hid/index
docs: i2c: convert to ReST and add to driver-api bookset Convert each file at I2C subsystem, renaming them to .rst and adding to the driver-api book. Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org> Acked-by: Wolfram Sang <wsa@the-dreams.de> Acked-by: Alexandre Belloni <alexandre.belloni@bootlin.com> Acked-by: Jonathan Cameron <Jonathan.Cameron@huawei.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2019-07-26 15:51:16 +03:00
i2c/index
docs: add some documentation dirs to the driver-api book Those are subsystem docs, with a mix of kABI and user-faced docs. While they're not split, keep the dirs where they are, adding just a pointer to the main index. Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
2019-06-18 23:16:23 +03:00
iio/index
docs: isdn: convert to ReST and add to kAPI bookset The ISDN documentation is a mix of admin guide, uAPI and kAPI. Ideally, it should be split. Yet, not sure if it would worth the troble. Anyway, we have the same kind of mix on several drivers specific documentation. So, just like the others, keep the directory at the root Documentation/ tree, just adding a pointer to it at the kAPI section, as the documentation was written with the Kernel developers in mind. Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2019-07-26 15:51:25 +03:00
isdn/index
docs: infiniband: add it to the driver-api bookset While this contains some uAPI stuff, it was intended to be read by a kernel doc. So, let's not move it to a different dir, but, instead, just add it to the driver-api bookset. Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org> Signed-off-by: Jason Gunthorpe <jgg@mellanox.com>
2019-06-28 15:30:28 +03:00
infiniband/index
docs: leds: add it to the driver-api book The contents of leds driver docs is messy: it has lots of admin-guide stuff and kernel internal ones, just like other driver subsystems. I'm opting to keep the dir at the same place and just add a link to it. This makes clearer that this require changes. Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
2019-06-18 22:51:34 +03:00
leds/index
doc-rst: add stand-alone conf.py to media folder With the media/conf.py, and media/index.rst the media folder can be build and distributed stand-alone. Signed-off-by: Markus Heiser <markus.heiser@darmarIT.de> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-08-13 17:12:43 +03:00
media/index
docs: add some directories to the main documentation index The contents of those directories were orphaned at the documentation body. While those directories could likely be moved to be inside some guide, I'm opting to just adding their indexes to the main one, removing the :orphan: and adding the SPDX header. For the drivers, the rationale is that the documentation contains a mix of Kernelspace, uAPI and admin-guide. So, better to keep them on separate directories, as we've be doing with similar subsystem-specific docs that were not split yet. For the others, well... I'm too lazy to do the move. Also, it seems to make sense to keep at least some of those at the main dir (like kbuild, for example). In any case, a latter patch could do the move. Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org> Acked-by: Bartlomiej Zolnierkiewicz <b.zolnierkie@samsung.com>
2019-06-28 14:36:50 +03:00
netlabel/index
docs-rst: convert networking book to ReST Use pandoc to convert documentation to ReST by calling Documentation/sphinx/tmplcvt script. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
2017-05-12 15:14:02 +03:00
networking/index
docs: add some directories to the main documentation index The contents of those directories were orphaned at the documentation body. While those directories could likely be moved to be inside some guide, I'm opting to just adding their indexes to the main one, removing the :orphan: and adding the SPDX header. For the drivers, the rationale is that the documentation contains a mix of Kernelspace, uAPI and admin-guide. So, better to keep them on separate directories, as we've be doing with similar subsystem-specific docs that were not split yet. For the others, well... I'm too lazy to do the move. Also, it seems to make sense to keep at least some of those at the main dir (like kbuild, for example). In any case, a latter patch could do the move. Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org> Acked-by: Bartlomiej Zolnierkiewicz <b.zolnierkie@samsung.com>
2019-06-28 14:36:50 +03:00
pcmcia/index
docs: power: add it to to the main documentation index The power docs are orphaned at the documentation body. While it could likely be moved to be inside some guide, I'm opting to just adding it to the main index.rst, removing the :orphan: and adding the SPDX header. The reason is similar to what it was done for other driver-specific subsystems: the docs there contain a mix of Kernelspace, uAPI and admin-guide. So, better to keep them on its own directory, while the docs there are not properly classified. Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
2019-07-15 15:39:57 +03:00
power/index
docs: add some directories to the main documentation index The contents of those directories were orphaned at the documentation body. While those directories could likely be moved to be inside some guide, I'm opting to just adding their indexes to the main one, removing the :orphan: and adding the SPDX header. For the drivers, the rationale is that the documentation contains a mix of Kernelspace, uAPI and admin-guide. So, better to keep them on separate directories, as we've be doing with similar subsystem-specific docs that were not split yet. For the others, well... I'm too lazy to do the move. Also, it seems to make sense to keep at least some of those at the main dir (like kbuild, for example). In any case, a latter patch could do the move. Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org> Acked-by: Bartlomiej Zolnierkiewicz <b.zolnierkie@samsung.com>
2019-06-28 14:36:50 +03:00
target/index
timers/index
watchdog/index
docs: virtual: add it to the documentation body As files are getting converted to ReST, add them to the documentation body. Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
2019-06-18 21:13:40 +03:00
virtual/index
docs-rst: add input docs at main index and use kernel-figure The input subsystem documentation got converted into ReST. Add it to the main documentation index and use kernel-figure for the two svg images there. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-04-11 13:01:19 +03:00
input/index
docs: hwmon: Add an index file and rename docs to *.rst Now that all files were converted to ReST format, rename them and add an index. Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org> Signed-off-by: Guenter Roeck <linux@roeck-us.net>
2019-04-17 12:46:29 +03:00
hwmon/index
Documentation/gpu: add new gpu.rst converted from DocBook gpu.tmpl This is the first step towards converting the DocBook gpu.tmpl to Sphinx and reStructuredText, the new kernel documentation tool and markup. Use Jon's "cheesy conversion script" in Documentation/sphinx/tmplcvt to do the rough conversion. Do the manual edits in follow-up patches. Add a new Documentation/gpu directories for the graphics related documentation. (Hooray, now we can have directories based on topics rather than tools under Documentation.) We also won't remove the DocBook gpu.tmpl yet so it's easier to build both and compare the results for parity. Signed-off-by: Jani Nikula <jani.nikula@intel.com> Signed-off-by: Daniel Vetter <daniel.vetter@ffwll.ch> Link: http://patchwork.freedesktop.org/patch/msgid/bc7b4f9ac037632e0c8469c079d21fad5eaa39a0.1466506505.git.jani.nikula@intel.com
2016-06-21 14:48:57 +03:00
gpu/index
tpm: move documentation under Documentation/security In order too make Documentation root directory cleaner move the tpm directory under Documentation/security. Signed-off-by: Jarkko Sakkinen <jarkko.sakkinen@linux.intel.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-11-04 02:57:52 +03:00
security/index
ALSA: doc: ReSTize alsa-driver-api document A simple conversion of alsa-driver-api document from DocBook to ReST. It's moved to the new Documentation/sound/kernel-api subdirectory that will contain other ALSA kernel API documents. The GPL legal note was removed, as it's superfluous (and doesn't fit with ReST kernel docs pretty well). Signed-off-by: Takashi Iwai <tiwai@suse.de>
2016-11-02 23:30:39 +03:00
sound/index
crypto: doc - convert crypto API documentation to Sphinx With the conversion of the kernel crypto API DocBook to Sphinx, the monolithic document is broken up into individual documents. The documentation is unchanged with the exception of a slight reordering to keep the individual document parts self-contained. Signed-off-by: Stephan Mueller <smueller@chronox.de> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-10-21 05:54:22 +03:00
crypto/index
docs-rst: convert filesystems book to ReST Use pandoc to convert documentation to ReST by calling Documentation/sphinx/tmplcvt script. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
2017-05-12 12:50:22 +03:00
filesystems/index
docs/vm: add index.rst and link MM documentation to top level index Signed-off-by: Mike Rapoport <rppt@linux.vnet.ibm.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2018-03-21 22:22:48 +03:00
vm/index
docs: Add bpf/index to top level index Recently bpf docs were converted to RST format. The new files were not added to the top level toctree. This causes build system to emit a warning of type WARNING: document isn't included in any toctree Add bpf/index.rst to Documentation/index.rst Signed-off-by: Tobin C. Harding <me@tobin.cc> Signed-off-by: Daniel Borkmann <daniel@iogearbox.net>
2018-07-26 08:03:04 +03:00
bpf/index
docs: usb: rename files to .rst and add them to drivers-api While there are a mix of things here, most of the stuff were written from Kernel developer's PoV. So, add them to the driver-api book. A follow up for this patch would be to move documents from there that are specific to sysadmins, adding them to the admin-guide. Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org> Acked-by: Johan Hovold <johan@kernel.org> Acked-by: Felipe Balbi <felipe.balbi@linux.intel.com> Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
2019-06-19 00:05:38 +03:00
usb/index
Documentation: add Linux PCI to Sphinx TOC tree Add index.rst for PCI subsystem. More docs will be added later. Signed-off-by: Changbin Du <changbin.du@gmail.com> Signed-off-by: Bjorn Helgaas <bhelgaas@google.com>
2019-05-14 17:47:23 +03:00
PCI/index
Documentation: add ibmvmc to toctree(index) and fix warnings Fix Sphinx warnings in ibmvmc.rst, add an index.rst file in Documentation/misc-devices/, and insert that index file into the top-level index file. Documentation/misc-devices/ibmvmc.rst:2: WARNING: Explicit markup ends without a blank line; unexpected unindent. Documentation/misc-devices/ibmvmc.rst:: WARNING: document isn't included in any toctree Signed-off-by: Randy Dunlap <rdunlap@infradead.org> Cc: Steven Royer <seroyer@linux.ibm.com> Cc: Jonathan Corbet <corbet@lwn.net> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2019-01-14 06:21:46 +03:00
misc-devices/index
docs: driver-api: add remaining converted dirs to it There are a number of driver-specific descriptions that contain a mix of userspace and kernelspace documentation. Just like we did with other similar subsystems, add them at the driver-api groupset, but don't move the directories. Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
2019-04-22 22:49:11 +03:00
mic/index
scheduler/index
Documentation/sphinx: add basic working Sphinx configuration and build Add basic configuration and makefile to build documentation from any .rst files under Documentation using Sphinx. For starters, there's just the placeholder index.rst. At the top level Makefile, hook Sphinx documentation targets alongside (but independent of) the DocBook toolchain, having both be run on the various 'make *docs' targets. All Sphinx processing is placed into Documentation/Makefile.sphinx. Both that and the Documentation/DocBook/Makefile are now expected to handle all the documentation targets, explicitly ignoring them if they're not relevant for that particular toolchain. The changes to the existing DocBook Makefile are kept minimal. There is graceful handling of missing Sphinx and rst2pdf (which is needed for pdf output) by checking for the tool and python module, respectively, with informative messages to the user. If the Read the Docs theme (sphinx_rtd_theme) is available, use it, but otherwise gracefully fall back to the Sphinx default theme, with an informative message to the user, and slightly less pretty HTML output. Sphinx can now handle htmldocs, pdfdocs (if rst2pdf is available), epubdocs and xmldocs targets. The output documents are written into per output type subdirectories under Documentation/output. Finally, you can pass options to sphinx-build using the SPHINXBUILD make variable. For example, 'make SPHINXOPTS=-v htmldocs' for more verbose output from Sphinx. This is based on the original work by Jonathan Corbet, but he probably wouldn't recognize this as his own anymore. Signed-off-by: Jani Nikula <jani.nikula@intel.com>
2016-05-19 15:14:05 +03:00
docs-rst: convert sh book to ReST Use pandoc to convert documentation to ReST by calling Documentation/sphinx/tmplcvt script. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
2017-05-13 13:50:43 +03:00
Architecture-specific documentation
-----------------------------------
These books provide programming details about architecture-specific
implementation.
.. toctree::
:maxdepth: 2
sh/index
docs: add arch doc directories to the index Now that several arch documents were converted to ReST, add their indexes to Documentation/index.rst and remove the :orphan: from them. Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
2019-04-22 22:10:26 +03:00
arm/index
arm64/index
ia64/index
m68k/index
docs: powerpc: convert docs to ReST and rename to *.rst Convert docs to ReST and add them to the arch-specific book. The conversion here was trivial, as almost every file there was already using an elegant format close to ReST standard. The changes were mostly to mark literal blocks and add a few missing section title identifiers. One note with regards to "--": on Sphinx, this can't be used to identify a list, as it will format it badly. This can be used, however, to identify a long hyphen - and "---" is an even longer one. At its new index.rst, let's add a :orphan: while this is not linked to the main index.rst file, in order to avoid build warnings. Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org> Acked-by: Andrew Donnellan <andrew.donnellan@au1.ibm.com> # cxl
2019-04-10 14:32:42 +03:00
powerpc/index
docs: mips: add to the documentation body as ReST Manually convert the AU1xxx_IDE.README file to ReST and add to a MIPS book as part of the main documentation body. Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org> Acked-by: Paul Burton <paul.burton@mips.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2019-07-26 15:51:31 +03:00
mips/index
docs: openrisc: convert to ReST and add to documentation body Manually convert the two openRisc documents to ReST, adding them to the Linux documentation body. Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org> Acked-by: Stafford Horne <shorne@gmail.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2019-07-26 15:51:24 +03:00
openrisc/index
docs: parisc: convert to ReST and add to documentation body Manually convert the two PA-RISC documents to ReST, adding them to the Linux documentation body. Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2019-07-26 15:51:23 +03:00
parisc/index
docs: add arch doc directories to the index Now that several arch documents were converted to ReST, add their indexes to Documentation/index.rst and remove the :orphan: from them. Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
2019-04-22 22:10:26 +03:00
riscv/index
s390/index
sh/index
sparc/index
x86/speculation/mds: Add mds_clear_cpu_buffers() The Microarchitectural Data Sampling (MDS) vulernabilities are mitigated by clearing the affected CPU buffers. The mechanism for clearing the buffers uses the unused and obsolete VERW instruction in combination with a microcode update which triggers a CPU buffer clear when VERW is executed. Provide a inline function with the assembly magic. The argument of the VERW instruction must be a memory operand as documented: "MD_CLEAR enumerates that the memory-operand variant of VERW (for example, VERW m16) has been extended to also overwrite buffers affected by MDS. This buffer overwriting functionality is not guaranteed for the register operand variant of VERW." Documentation also recommends to use a writable data segment selector: "The buffer overwriting occurs regardless of the result of the VERW permission check, as well as when the selector is null or causes a descriptor load segment violation. However, for lowest latency we recommend using a selector that indicates a valid writable data segment." Add x86 specific documentation about MDS and the internal workings of the mitigation. Signed-off-by: Thomas Gleixner <tglx@linutronix.de> Reviewed-by: Borislav Petkov <bp@suse.de> Reviewed-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org> Reviewed-by: Frederic Weisbecker <frederic@kernel.org> Reviewed-by: Jon Masters <jcm@redhat.com> Tested-by: Jon Masters <jcm@redhat.com>
2019-02-19 01:13:06 +03:00
x86/index
docs: add arch doc directories to the index Now that several arch documents were converted to ReST, add their indexes to Documentation/index.rst and remove the :orphan: from them. Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
2019-04-22 22:10:26 +03:00
xtensa/index
docs-rst: convert sh book to ReST Use pandoc to convert documentation to ReST by calling Documentation/sphinx/tmplcvt script. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
2017-05-13 13:50:43 +03:00
docs: create filesystem internal section Create a new top-level section for documentation of filesystem usage, on-disk format information, and anything else. Signed-off-by: Darrick J. Wong <darrick.wong@oracle.com> Signed-off-by: Theodore Ts'o <tytso@mit.edu>
2018-07-29 23:14:02 +03:00
Filesystem Documentation
------------------------
The documentation in this section are provided by specific filesystem
subprojects.
.. toctree::
docs: fix up the obviously obsolete bits in the new ext4 documentation Signed-off-by: Theodore Ts'o <tytso@mit.edu>
2018-07-29 23:35:23 +03:00
:maxdepth: 2
docs: create filesystem internal section Create a new top-level section for documentation of filesystem usage, on-disk format information, and anything else. Signed-off-by: Darrick J. Wong <darrick.wong@oracle.com> Signed-off-by: Theodore Ts'o <tytso@mit.edu>
2018-07-29 23:14:02 +03:00
filesystems/ext4/index
doc: move away translations from top-level index In translations/ we have now a dedicated index.rst where we add/remove references to translations. Translations are in English alphabetical order. Signed-off-by: Federico Vaga <federico.vaga@vaga.pv.it> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2018-06-06 01:49:00 +03:00
Translations
------------
docs/zh_CN: Add coding-style into docs build system Tested by the command: make htmldocs During the compiling process, zh_CN/coding-style.rst has no errors and warnings generated, the generated html document has been checked. Signed-off-by: Andy Deng <theandy.deng@gmail.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-01-25 07:14:33 +03:00
.. toctree::
doc: move away translations from top-level index In translations/ we have now a dedicated index.rst where we add/remove references to translations. Translations are in English alphabetical order. Signed-off-by: Federico Vaga <federico.vaga@vaga.pv.it> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2018-06-06 01:49:00 +03:00
:maxdepth: 2
Documentation: Add HOWTO Japanese translation into rst based build system This commit adds Japanese translation of HOWTO document into rst based documentation build system with updates. Signed-off-by: Tsugikazu Shibata <tshibata@ab.jp.nec.com> Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-04-08 13:24:04 +03:00
doc: move away translations from top-level index In translations/ we have now a dedicated index.rst where we add/remove references to translations. Translations are in English alphabetical order. Signed-off-by: Federico Vaga <federico.vaga@vaga.pv.it> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2018-06-06 01:49:00 +03:00
translations/index
Documentation: Add HOWTO Japanese translation into rst based build system This commit adds Japanese translation of HOWTO document into rst based documentation build system with updates. Signed-off-by: Tsugikazu Shibata <tshibata@ab.jp.nec.com> Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-04-08 13:24:04 +03:00
Documentation/sphinx: add basic working Sphinx configuration and build Add basic configuration and makefile to build documentation from any .rst files under Documentation using Sphinx. For starters, there's just the placeholder index.rst. At the top level Makefile, hook Sphinx documentation targets alongside (but independent of) the DocBook toolchain, having both be run on the various 'make *docs' targets. All Sphinx processing is placed into Documentation/Makefile.sphinx. Both that and the Documentation/DocBook/Makefile are now expected to handle all the documentation targets, explicitly ignoring them if they're not relevant for that particular toolchain. The changes to the existing DocBook Makefile are kept minimal. There is graceful handling of missing Sphinx and rst2pdf (which is needed for pdf output) by checking for the tool and python module, respectively, with informative messages to the user. If the Read the Docs theme (sphinx_rtd_theme) is available, use it, but otherwise gracefully fall back to the Sphinx default theme, with an informative message to the user, and slightly less pretty HTML output. Sphinx can now handle htmldocs, pdfdocs (if rst2pdf is available), epubdocs and xmldocs targets. The output documents are written into per output type subdirectories under Documentation/output. Finally, you can pass options to sphinx-build using the SPHINXBUILD make variable. For example, 'make SPHINXOPTS=-v htmldocs' for more verbose output from Sphinx. This is based on the original work by Jonathan Corbet, but he probably wouldn't recognize this as his own anymore. Signed-off-by: Jani Nikula <jani.nikula@intel.com>
2016-05-19 15:14:05 +03:00
Indices and tables
==================
* :ref:`genindex`
Reference in New Issue Copy Permalink