commit 0283189e8f3d0917e2ac399688df85211f48447b upstream.
Sphinx 6.0 removed the execfile_() function, which we use as part of the
configuration process. They *did* warn us... Just open-code the
functionality as is done in Sphinx itself.
Tested (using SPHINX_CONF, since this code is only executed with an
alternative config file) on various Sphinx versions from 2.5 through 6.0.
Reported-by: Martin Liška <mliska@suse.cz>
Cc: stable@vger.kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
commit 551bd3368a7b3cfef01edaade8970948d178d40a upstream.
With Sphinx 2.0 (or prior versions with the deprecation warnings fixed) the
docs build fails with:
Documentation/gpu/i915.rst:403: WARNING: Title level inconsistent:
Global GTT Fence Handling
~~~~~~~~~~~~~~~~~~~~~~~~~
reST markup error:
Documentation/gpu/i915.rst:403: (SEVERE/4) Title level inconsistent:
I "fixed" it by changing the subsections in i915.rst, but that didn't seem
like the correct change. It turns out that a couple of i915 files create
their own subsections in kerneldoc comments using apostrophes as the
heading marker:
Layout
''''''
That breaks the normal subsection marker ordering, and newer Sphinx is
rather more strict about enforcing that ordering. So fix the offending
comments to make Sphinx happy.
(This is unfortunate, in that kerneldoc comments shouldn't need to be aware
of where they might be included in the heading hierarchy, but I don't see
a better way around it).
Cc: stable@vger.kernel.org # v4.14+
Acked-by: Jani Nikula <jani.nikula@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
commit 096ea522e84ea68f8e6c41e5e7294731a81e29bc upstream.
Recent versions of sphinx will emit messages like:
Documentation/sphinx/kerneldoc.py:103:
RemovedInSphinx20Warning: app.warning() is now deprecated.
Use sphinx.util.logging instead.
Switch to sphinx.util.logging to make this unsightly message go away.
Alas, that interface was only added in version 1.6, so we have to add a
version check to keep things working with older sphinxes.
Cc: stable@vger.kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
commit 2404dad1f67f8917e30fc22a85e0dbcc85b99955 upstream.
AutoReporter is going away; recent versions of sphinx emit a warning like:
Documentation/sphinx/kerneldoc.py:125:
RemovedInSphinx20Warning: AutodocReporter is now deprecated.
Use sphinx.util.docutils.switch_source_input() instead.
Make the switch. But switch_source_input() only showed up in 1.7, so we
have to do ugly version checks to keep things working in older versions.
Cc: stable@vger.kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
commit 3bc8088464712fdcb078eefb68837ccfcc413c88 upstream.
Our version check in Documentation/conf.py never envisioned a world where
Sphinx moved beyond 1.x. Now that the unthinkable has happened, fix our
version check to handle higher version numbers correctly.
Cc: stable@vger.kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
This contains a set of early-boot memory-management docs from Mike
Rapoport. It's been circulating on linux-mm for a long time; I finally
picked it up even though it changes a lot of .c files under mm/ (comments
only).
Two jump tags were misspelled, leading to non-working cross-reference
links.
Reported-by: Federico Vaga <federico.vaga@vaga.pv.it>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
-rc1 broke the docs build due to changes in the e100/e1000 drivers; -rc3
got the fixes via the networking tree. Pull in -rc3 so that the docs tree
can actually build the docs again.
Now that we have kerneldoc comments for
memalloc_no{fs,io}_{save_restore}(), go ahead and pull them into the docs.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
The removal of this file appears to have been premature; it's not a feature
enabled by Kconfig, but it's a arch-level feature regardless. Put it back
for now until some happy future time when we decide how we really want to
document such features.
This reverts commit 2bef69a385.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Merge -rc2 to pick up the changes to
Documentation/core-api/kernel-api.rst that hit mainline via the
networking tree. In their absence, subsequent patches cannot be
applied.
Thomas said:
There are a few bogus SPDX identifiers in various files and SPDX
Identifiers used in tree or about to be used which have no corresponding
License Text file in the LICENSES directory or use the new variant of the
GPL-2.0[+] license identifiers which are not mentioned in the GPL-2.0
Valid-License-Identifiers: tags.
There is no tool which can be used to scan the tree and also nothing which
helps people who submit patches to check their stuff before submission.
The following series cleans that up:
- Add GPL-2.0-only and GPL-2.0-or-later identifiers to the GPL2.0 license
and the Linux-syscall-note exception
- Add X11, Apache-2.0, CC-BY-SA-4.0, CCDL-1.0, Linux-OpenIB license texts
to the LICENSES directory along with the required documentation texts
- Add a checker script which can read a single file or even a patch from
the command line or does a full git tree scan
[Thomas also wins some sort of special prize for including an SPDX-checking
patch that complains about itself!]
Networking docs changes go through the networking tree, so patch the
MAINTAINERS file to direct authors to the right place.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: David S. Miller <davem@davemloft.net>
Mike Rapoport says:
These patches convert files in Documentation/vm to ReST format, add an
initial index and link it to the top level documentation.
There are no contents changes in the documentation, except few spelling
fixes. The relatively large diffstat stems from the indentation and
paragraph wrapping changes.
I've tried to keep the formatting as consistent as possible, but I could
miss some places that needed markup and add some markup where it was not
necessary.
[jc: significant conflicts in vm/hmm.rst]
Kernel.org nicely maintains an online copy of the formatted documentation;
tell our users that it exists.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
So once upon a time I set out to fix the problem reported by Tobin wherein
a literal block within a kerneldoc comment would be corrupted in
processing. On the way, though, I got annoyed at the way I have to learn
how kernel-doc works from the beginning every time I tear into it.
As a result, seven of the following eight patches just get rid of some dead
code and reorganize the rest - mostly turning the 500-line process_file()
function into something a bit more rational. Sphinx output is unchanged
after these are applied. Then, at the end, there's a tweak to stop messing
with literal blocks.
If anybody was unaware that I've not done any serious Perl since the
1990's, they will certainly understand that fact now.
Add the SPDX header while I'm in the neighborhood. The source itself just
says "GNU General Public License", but it also refers people to the COPYING
file for further information. Since COPYING says 2.0-only, that is what I
have put into the header.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
It can be useful to put code snippets into kerneldoc comments; that can be
done with the "::" operator at the end of a line like this::
if (desperate)
run_in_circles();
The ".. code-block::" directive can also be used to this end. kernel-doc
currently fails to understand these literal blocks and applies its normal
markup to them, which is then treated as literal by sphinx. The result is
unsightly markup instead of a useful code snippet.
Apply a hack to the output code to recognize literal blocks and avoid
performing any special markup on them. It's ugly, but that means it fits
in well with the rest of the script.
Reviewed-by: Jani Nikula <jani.nikula@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Move STATE_INLINE and STATE_DOCBLOCK code out of process_file(), which now
actually fits on a single screen. Delete an unused variable and add a
couple of comments while I'm at it.
Reviewed-by: Jani Nikula <jani.nikula@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Move the top-level prototype-processing code out of process_file().
Reviewed-by: Jani Nikula <jani.nikula@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Also group the pseudo-global $leading_space variable with its peers.
Reviewed-by: Jani Nikula <jani.nikula@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Move this code out of process_file() in the name of readability and
maintainability.
Reviewed-by: Jani Nikula <jani.nikula@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Begin the process of splitting up the nearly 500-line process_file()
function by moving STATE_NORMAL processing to a separate function.
Reviewed-by: Jani Nikula <jani.nikula@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
STATE_FIELD describes a parser state that can handle any part of a
kerneldoc comment body; rename it to STATE_BODY to reflect that.
The $in_purpose variable was a hidden substate of STATE_FIELD; get rid of
it and make a proper state (STATE_BODY_MAYBE) instead. This will make the
subsequent process_file() splitup easier.
Reviewed-by: Jani Nikula <jani.nikula@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
XML escaping is a worry that came with DocBook, which we no longer have any
dealings with. So get rid of the useless xml_escape()/xml_unescape()
functions. No change to the generated output.
Reviewed-by: Jani Nikula <jani.nikula@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Commit ca986ad9bc (nl80211: allow multiple active scheduled scan
requests) removed WIPHY_FLAG_SUPPORTS_SCHED_SCAN but left the kerneldoc
description in place, leading to this docs-build warning:
./include/net/cfg80211.h:3278: warning: Excess enum value
'WIPHY_FLAG_SUPPORTS_SCHED_SCAN' description in 'wiphy_flags'
Remove the line and gain a bit of peace.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Acked-by: Arend van Spriel <arend.vanspriel@broadcom.com>
Signed-off-by: Johannes Berg <johannes.berg@intel.com>
This warning will happen for every normal kernel docs build and doesn't
carry any useful information. Should anybody actually depend on this
"version" variable (which isn't clear to me), the "unknown version" value
will be clue enough.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
A couple of structures in <linux/usb/gadget.h> have incomplete kerneldoc
comments, leading to these warnings in the docs build:
./include/linux/usb/gadget.h:230: warning: No description found for parameter 'claimed'
./include/linux/usb/gadget.h:230: warning: No description found for parameter 'enabled'
./include/linux/usb/gadget.h:412: warning: No description found for parameter 'quirk_altset_not_supp'
./include/linux/usb/gadget.h:412: warning: No description found for parameter 'quirk_stall_not_supp'
./include/linux/usb/gadget.h:412: warning: No description found for parameter 'quirk_zlp_not_supp'
Document those fields to make the warnings go away.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Felipe Balbi <felipe.balbi@linux.intel.com>
Tom Saeger says:
Recently, while reading up on binfmt I attempted to open a document ref
only to find it was invalid. I did a quick grep, found all the
binfmt_misc related broken refs and sent a patch.
Fine. Easy.
Then I wondered, "how many broken doc refs are there?".
Turns out with all the recent doc moves, quite a few.
I went about fixing just those found in Documentation/,
except those in Documentation/translations/ and
Documentation/devicetree/ for now.
Most of these changes were s/txt/rst/ or fixing up a path to an obvious
new location. Some required going back to v4.10 v4.4 or some other
version to sleuth-out what content was actually being referenced and
then fixing the reference to point to the new file with that content.
The kerneldoc comment for the genpool_algo_t typedef was incomplete and
incorrectly formatted, leading to a raft of warnings during the docs build.
Fix it appropriately.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Genalloc/genpool has kerneldoc comments, but nothing has ever been pulled
into the docs themselves. Here's a first attempt, repurposed from an
article I wrote at https://lwn.net/Articles/729653/.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Commit 5657933dbb (treewide: Move dma_ops from struct dev_archdata into
struct device) added the dma_ops field to struct device, but did not
update the kerneldoc comment, yielding this warning:
./include/linux/device.h:969: warning: No description found for parameter 'dma_ops'
Add a description and bring a little peace to the world.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Reviewed-by: Bart Van Assche <bart.vanassche@wdc.com>
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
The kerneldoc comment for scsi_initialize_rq() neglected to document the
"rq" parameter, leading to this docs build warning:
./drivers/scsi/scsi_lib.c:1116: warning: No description found for parameter 'rq'
Document the parameter and make the build slightly quieter.
[mkp: used wording suggested by Bart]
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Martin K. Petersen <martin.petersen@oracle.com>
The kerneldoc description for the trig_readonly field of struct iio_dev
lacked a colon, leading to this doc build warning:
./include/linux/iio/iio.h:603: warning: No description found for parameter 'trig_readonly'
A similar issue for iio_trigger_set_immutable() in trigger.h yielded:
./include/linux/iio/trigger.h:151: warning: No description found for parameter 'indio_dev'
./include/linux/iio/trigger.h:151: warning: No description found for parameter 'trig'
Fix the formatting and silence the warnings.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Jonathan Cameron <Jonathan.Cameron@huawei.com>
Commit 0b4773fd16 (mtd: nand: Drop unused cached programming support)
removed the "cached" parameter from nand_write_page(), but did not update
the kerneldoc comments, creating this docs build warning:
./drivers/mtd/nand/nand_base.c:2751: warning: Excess function parameter 'cached' description in 'nand_write_page'
Remove the offending line so we can have a little peace and quiet.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Boris Brezillon <boris.brezillon@free-electrons.com>
The kerneldoc comments for a couple of functions in drivers/ata/libata-eh.c
had fallen behind the current implementation, resulting in these doc build
warnings:
./drivers/ata/libata-eh.c:1449: warning: No description found for parameter 'link'
./drivers/ata/libata-eh.c:1449: warning: Excess function parameter 'ap' description in 'ata_eh_done'
./drivers/ata/libata-eh.c:1590: warning: No description found for parameter 'qc'
./drivers/ata/libata-eh.c:1590: warning: Excess function parameter 'dev' description in 'ata_eh_request_sense'
Update the comments and make the warnings go away.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Tejun Heo <tj@kernel.org>
A couple of kerneldoc comments in <linux/wait.h> had incorrect names for
macro parameters, with this unsightly result:
./include/linux/wait.h:555: warning: No description found for parameter 'wq'
./include/linux/wait.h:555: warning: Excess function parameter 'wq_head' description in 'wait_event_interruptible_hrtimeout'
./include/linux/wait.h:759: warning: No description found for parameter 'wq_head'
./include/linux/wait.h:759: warning: Excess function parameter 'wq' description in 'wait_event_killable'
Correct the comments and kill the warnings.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Cc: Linus Torvalds <torvalds@linux-foundation.org>
Cc: Peter Zijlstra <peterz@infradead.org>
Cc: Thomas Gleixner <tglx@linutronix.de>
Cc: linux-doc@vger.kernel.org
Link: http://lkml.kernel.org/r/20170724135800.769c4042@lwn.net
Signed-off-by: Ingo Molnar <mingo@kernel.org>
Documentation/gpu/drm-mm.rst includes from include/drm/drm_syncobj.h with
:export:, but this is a header file without export directives. That
results in this warning:
./include/drm/drm_syncobj.h:1: warning: no structured comments found
...and a failure to obtain the documentation from that file. Switch to
:internal: instead to make both problems go away.
Cc: dri-devel@lists.freedesktop.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Mauro says:
Sphinx installation is not trivial, as not all versions are supported,
and it requires a lot of stuff for math, images and PDF/LaTeX output
to work.
So, add a script that checks if everything is fine, providing
distro-specific hints about what's needed for it to work.
The only function of interest in that file was scsi_print_status(). That
function was removed in commit 7ac7076344 (scsi: remove
scsi_print_status()) but the docs were not changed to match, yielding this
warning:
./drivers/scsi/constants.c:1: warning: no structured comments found
There's nothing there anymore, so just remove that section from the docs.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Back in 2012, commit 9807f75955 (UAPI: (Scripted) Disintegrate
arch/s390/include/asm) moved struct cmbdata (and its kerneldoc comments) to
another file, but did not update the docs to match. The result is this
warning:
./arch/s390/include/asm/cmb.h:1: warning: no structured comments found
...and no documentation for that structure. Update the docs to get the
information from the right place.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
There are no kerneldoc comments in drivers/dma-buf/seqno-fence.c, and it
appears there never have been. Stop looking for comments there to
eliminate this warning:
./drivers/dma-buf/seqno-fence.c:1: warning: no structured comments found
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
...because there are none there, and I cannot figure out what would ever
have been of interest there. This eliminates this warning:
./kernel/sys.c:1: warning: no structured comments found
from the build.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
The docs build complains:
./include/linux/init.h:1: warning: no structured comments found
The problem is that the comments in question were moved to module.h in
commit 0fd972a7d9 (module: relocate module_init from init.h to
module.h). Fix basics.rst to match.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
The input docs enable section numbering at multiple levels, leading to a
lot of bright-red "nested numbered toctree" warnings in newer Sphinx
versions. Just take that directive out for now to help alleviate the
global red-pixel shortage.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Documentation/core-api/kernel-api.rst was including kerneldoc comments from
arch/x86/include/asm/uaccess_32.h, but the relevant comments moved to
.../uaccess.h some time ago. Correct the include to pick up the comments
and eliminate a warning.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
That file went away with commit bd8cc5a062 (srcu: Remove Classic SRCU)
during the 4.13 merge window, leading to errors like:
Error: Cannot open file ./kernel/rcu/srcu.c
during the docs build.
Reported-by: Linus Torvalds <torvalds@linux-foundation.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
There were a few bits and pieces left over from the now-disused DocBook
toolchain; git rid of them.
Reported-by: Markus Heiser <markus.heiser@darmarit.de>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
...otherwise the PDF build fails when it can't find constraints.pdf.
Acked-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Two table problems caused the PDF build to fail:
- Evidently multirow cells are not appreciated in table headers,
so remove such from the "CS Rows" table.
- The logging message structure table was incorrectly formatted,
with two "+" instead of "|". The HTML build is forgiving of such
things, but PDF is not.
Acked-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Otherwise we get PDF build failures when LaTeX refused to acknowledge the
existence of \ifthenelse
Fixes: 41cff161fe
Cc: Mauro Carvalho Chehab <mchehab@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Mauro says:
This patch series convert the remaining DocBooks to ReST.
The first version was originally
send as 3 patch series:
[PATCH 00/36] Convert DocBook documents to ReST
[PATCH 0/5] Convert more books to ReST
[PATCH 00/13] Get rid of DocBook
The lsm book was added as if it were a text file under
Documentation. The plan is to merge it with another file
under Documentation/security, after both this series and
a security Documentation patch series gets merged.
It also adjusts some Sphinx-pedantic errors/warnings on
some kernel-doc markups.
I also added some patches here to add PDF output for all
existing ReST books.
The white space in the big enumerated list was inconsistent, leading to
some strange formatting artifacts.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
This is a straightforward conversion, without any real textual changes.
Since this document has seen no substantive changes since its addition in
2006, some such changes are probably warranted.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
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>
A fairly straightforward conversion to RST; the document is then added to
the driver-api manual.
Of course, this document has seen no substantive changes since 2008, so
chances are it needs work in other areas as well.
Cc: Mark Brown <broonie@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Convert deviceiobook.tmpl to RST and incorporate it into the driver API
manual.
Like the rest of our documentation, this one could use some work. There's
no mention of ioremap() and friends, no mention of io_read*() and friends.
But we have nice documentation for all those folks writing new drivers that
do port I/O :).
The :c:func: notation has been left off of all the read*/write* functions.
There's no kerneldoc comments for them anyway, so those links will never be
live, and writing a bunch of repetitive "read a byte from I/O memory"
comments lacks appeal.
Cc: Matthew Wilcox <willy@infradead.org>
Cc: Alan Cox <gnomes@lxorguk.ukuu.org.uk>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Convert the tracepoint docbook template to RST and add it to the core-api
manual. No changes to the actual text beyond the mechanical formatting
conversion.
Cc: Jason Baron <jbaron@redhat.com>
Cc: William Cohen <wcohen@redhat.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Add the appropriate markup to get the kerneldoc comments out of
lib/debugobjects.c that have never seen the light of day until now.
A logical next step, left for the reader at the moment, is to move the
function descriptions *out* of debug-objects.rst and into the kerneldoc
comments themselves.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
A couple of the most minor heading tweaks, otherwise no changes to the text
itself beyond the mechanical conversion.
Note that the inclusion of the kerneldoc comments from the source has never
worked, since exported symbols were asked for and none of those functions
are exported to modules. It doesn't work here either :)
Cc: Thomas Gleixner <tglx@linutronix.de>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Put this documentation with the other driver docs and try to keep the top
level reasonably clean.
Cc: Johannes Berg <johannes.berg@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Mauro says:
This series address a series of errors during PDF generation from
media documentation.
The first patch fixes the late redefinition of a LaTeX command at the
Sphinx LaTeX style that causes build to break when some cross-references
are used.
The next two patches fix PDF output issues with subdev-formats.rst.
The next 3 patches fix image includes and their output for PDF.
It is aligned with Linus request of not having binary-generated images
from their SVG source codes.
I still intend to move the remaing PNG images to vectorial ones (SVG),
as image scale works better, but this will require some additional work.
When done, I'll submit as a separate patch series.
It should also be noticed that the last patch violates the output dir,
when make is used with "O=some_dir", as Sphinx doesn't accept
image files outside the source directory. We'll likely need some Sphinx
extension in order to fix it, but at least with this series (plus Jani Nikola's
PDF fix series), the PDF output should work fine again.
[jc: added a commit fixing up a "make cleandocs" warning]
Recent Makefile changes added an rm command without the requisite "-f",
leading to warnings if the files do not exist. Make it be quiet again.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
It seems we can't have literal blocks in footnotes, which almost actually
makes some sense. So just use basic ``monospace`` instead.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
The creation of the admin and process guides is a great thing, but, without
care, we risk replacing a messy docs directory with a few messy Sphinx
books. In an attempt to head that off and show what I'm thinking, here's a
set of tweaks that, I think, make the existing Sphinx-formatted docs a bit
more accessible.
This is ancient stuff and we don't do things this way anymore. In the
absence of simply deleting the document, at least add a warning to it.
Reviewed-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
This is crufty stuff and should maybe just be deleted, but I'm not quite
ready to do that yet.
Reviewed-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
I believe this makes the page as a whole more approachable.
Reviewed-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
The main goal here was to get the subsections to show in the TOC as they do
for all the other documents. Also call out the DCO in the section title
since it's important.
Reviewed-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Put like documents together, with the essential ones at the top, and split
the TOC into sections.
Reviewed-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
The document has not been touched in over 11 years and doesn't reflect how
profiling is done in the perf era.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
The last release of this tool was for 2.6.28; it's hard to see how it has
any relevance to current kernels.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
The admin guide is a good start, but it's time to turn it into something
better than an unordered blob of files. This is a first step in that
direction. The TOC has been split up and annotated, the guides have been
reordered, and minor tweaks have been applied to a few of them.
One consequence of splitting up the TOC is that we don't really want to use
:numbered: anymore, since the count resets every time and there doesn't
seem to be a way to change that. Eventually we probably want to group the
documents into sub-books, at which point we can go back to a single TOC,
but it's probably early to do that.
Reviewed-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Let's make the title of this document (which shows up in the top page)
better describe its contents.
Cc: Jani Nikula <jani.nikula@intel.com>
Reviewed-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
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>
Merge Mauro's massive patch series creating the process and admin-guide
books. I think there's a lot of stuff to clean up here, but there's no
point in holding things up for that.
Mauro sez:
This patch series continues the efforts of converting the Linux Kernel
documentation to Sphinx.
It contains text to ReST conversion of several files under Documentation,
and a few ones under the main dir (README, REPORTING-BUGS).
All patches on this series can be found on my development tree:
https://git.linuxtv.org/mchehab/experimental.git/log/?h=lkml-books-v2
The Kernel docs html output after this series can be seen at:
https://mchehab.fedorapeople.org/kernel_docs/
Jonathan Corbet