summaryrefslogtreecommitdiff
path: root/Documentation/conf.py
AgeCommit message (Collapse)AuthorFilesLines
2020-06-08Replace HTTP links with HTTPS ones: documentationAlexander A. Klimov1-1/+1
Rationale: Reduces attack surface on kernel devs opening the links for MITM as HTTPS traffic is much harder to manipulate. Deterministic algorithm: For each file: For each line: If doesn't contain `\bxmlns\b`: For each link, `\bhttp://[^# \t\r\n]*(?:\w|/)`: If both the HTTP and HTTPS versions return 200 OK and serve the same content: Replace HTTP with HTTPS. Signed-off-by: Alexander A. Klimov <grandmaster@al2klimov.de> Link: https://lore.kernel.org/r/20200526060544.25127-1-grandmaster@al2klimov.de Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2020-04-21docs: LaTeX/PDF: drop list of documentsMauro Carvalho Chehab1-38/+0
The building system can auto-generate a list of documents since commit: 9d42afbe6bd4 ("docs: pdf: add all Documentation/*/index.rst to PDF output"). The added logic there allows keeping the existing list, but there's not real reason to keep it. Now, the media document has gone (it was split into tree). So, it sounds about time to get rid of the manual entries, and let the script to generate it automatically instead. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Link: https://lore.kernel.org/r/9345dba7164497dbf28578f6ec271e479379610c.1586881715.git.mchehab+huawei@kernel.org Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2020-03-21docs: conf.py: avoid thousands of duplicate label warning on SphinxMauro Carvalho Chehab1-0/+4
The autosectionlabel extension is nice, as it allows to refer to a section by its name without requiring any extra tag to create a reference name. However, on its default, it has two serious problems: 1) the namespace is global. So, two files with different "introduction" section would create a label with the same name. This is easily solvable by forcing the extension to prepend the file name with: autosectionlabel_prefix_document = True 2) It doesn't work hierarchically. So, if there are two level 1 sessions (let's say, one labeled "open" and another one "ioctl") and both have a level 2 "synopsis" label, both section 2 will have the same identical name. Currently, there's no way to tell Sphinx to create an hierarchical reference like: open / synopsis ioctl / synopsis This causes around 800 warnings. So, the fix should be to not let autosectionlabel to produce references for anything that it is not at a chapter level within any doc, with: autosectionlabel_maxdepth = 2 Fixes: 58ad30cf91f0 ("docs: fix reference to core-api/namespaces.rst") Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Link: https://lore.kernel.org/r/74f4d8d91c648d7101c45b4b99cc93532f4dadc6.1584716446.git.mchehab+huawei@kernel.org Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2020-03-19docs: fix reference to core-api/namespaces.rstJonathan Corbet1-1/+1
Fix a couple of dangling links to core-api/namespaces.rst by turning them into proper references. Enable the autosection extension (available since Sphinx 1.4) to make this work. Co-developed-by: Federico Vaga <federico.vaga@vaga.pv.it> Fixes: fcfacb9f8374 ("doc: move namespaces.rst from kbuild/ to core-api/") Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2019-10-02doc-rst: Programmatically render MAINTAINERS into ReSTKees Cook1-1/+2
In order to have the MAINTAINERS file visible in the rendered ReST output, this makes some small changes to the existing MAINTAINERS file to allow for better machine processing, and adds a new Sphinx directive "maintainers-include" to perform the rendering. Features include: - Per-subsystem reference links: subsystem maintainer entries can be trivially linked to both internally and external. For example: https://www.kernel.org/doc/html/latest/process/maintainers.html#secure-computing - Internally referenced .rst files are linked so they can be followed when browsing the resulting rendering. This allows, for example, the future addition of maintainer profiles to be automatically linked. - Field name expansion: instead of the short fields (e.g. "M", "F", "K"), use the indicated inline "full names" for the fields (which are marked with "*"s in MAINTAINERS) so that a rendered subsystem entry is more human readable. Email lists are additionally comma-separated. For example: SECURE COMPUTING Mail: Kees Cook <keescook@chromium.org> Reviewer: Andy Lutomirski <luto@amacapital.net>, Will Drewry <wad@chromium.org> SCM: git git://git.kernel.org/pub/scm/linux/kernel/git/kees/linux.git seccomp Status: Supported Files: kernel/seccomp.c include/uapi/linux/seccomp.h include/linux/seccomp.h tools/testing/selftests/seccomp/* tools/testing/selftests/kselftest_harness.h userspace-api/seccomp_filter Content regex: \bsecure_computing \bTIF_SECCOMP\b Signed-off-by: Kees Cook <keescook@chromium.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2019-07-17docs: conf.py: only use CJK if the font is availableMauro Carvalho Chehab1-2/+11
If we try to build a book with asian characters with XeLaTeX and the font is not available, it will produce an error. So, instead, add a logic at conf.py to detect if the proper font is installed. This will avoid an error while building the document, although the result may not be readable. Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
2019-07-17docs: conf.py: add CJK package needed by translationsMauro Carvalho Chehab1-0/+4
In order to be able to output Asian symbols with XeLaTeX, we need the xeCJK package, and a default font for CJK symbols. Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
2019-07-17docs: pdf: add all Documentation/*/index.rst to PDF outputMauro Carvalho Chehab1-0/+15
Currently, all index files should be manually added to the latex_documents array at conf.py. While this allows fine-tuning some LaTeX specific things, like the name of the output file and the name of the document, it is not uncommon to forget adding new documents there. So, add a logic that will seek for all Documentation/*/index.rst. If the index is not yet at latex_documents, it includes using a reasonable default. Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
2019-07-01Disable Sphinx SmartyPants in HTML outputStephen Kitt1-1/+1
The handling of dashes in particular results in confusing documentation in a number of instances, since "--" becomes an en-dash. This disables SmartyPants wholesale, losing smart quotes along with smart dashes. With Sphinx 1.6 we could fine-tune the conversion, using the new smartquotes and smartquotes_action settings. Signed-off-by: Stephen Kitt <steve@sk2.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2019-06-26Docs: An initial automarkup extension for sphinxJonathan Corbet1-1/+2
Rather than fill our text files with :c:func:`function()` syntax, just do the markup via a hook into the sphinx build process. Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2019-05-24docs: Fix conf.py for Sphinx 2.0Jonathan Corbet1-1/+1
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>
2018-10-24Merge tag 'docs-4.20' of git://git.lwn.net/linuxLinus Torvalds1-3/+3
Pull documentation updates from Jonathan Corbet: "This is a fairly typical cycle for documentation. There's some welcome readability improvements for the formatted output, some LICENSES updates including the addition of the ISC license, the removal of the unloved and unmaintained 00-INDEX files, the deprecated APIs document from Kees, more MM docs from Mike Rapoport, and the usual pile of typo fixes and corrections" * tag 'docs-4.20' of git://git.lwn.net/linux: (41 commits) docs: Fix typos in histogram.rst docs: Introduce deprecated APIs list kernel-doc: fix declaration type determination doc: fix a typo in adding-syscalls.rst docs/admin-guide: memory-hotplug: remove table of contents doc: printk-formats: Remove bogus kobject references for device nodes Documentation: preempt-locking: Use better example dm flakey: Document "error_writes" feature docs/completion.txt: Fix a couple of punctuation nits LICENSES: Add ISC license text LICENSES: Add note to CDDL-1.0 license that it should not be used docs/core-api: memory-hotplug: add some details about locking internals docs/core-api: rename memory-hotplug-notifier to memory-hotplug docs: improve readability for people with poorer eyesight yama: clarify ptrace_scope=2 in Yama documentation docs/vm: split memory hotplug notifier description to Documentation/core-api docs: move memory hotplug description into admin-guide/mm doc: Fix acronym "FEKEK" in ecryptfs docs: fix some broken documentation references iommu: Fix passthrough option documentation ...
2018-10-07docs: improve readability for people with poorer eyesightDarrick J. Wong1-3/+3
My eyesight is not in good shape, which means that I have difficulty reading the online Linux documentation. Specifically, body text is oddly small compared to list items and the contrast of various text elements is too low for me to be able to see easily. Therefore, alter the HTML theme overrides to make the text larger and increase the contrast for better visibility, and trust the typeface choices of the reader's browser. For the PDF output, increase the text size, use a sans-serif typeface for sans-serif text, and use a serif typeface for "roman" serif text. Signed-off-by: Darrick J. Wong <darrick.wong@oracle.com> Acked-by: Dave Chinner <dchinner@redhat.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2018-10-06docs: promote the ext4 data structures book to top levelDarrick J. Wong1-2/+2
Move the ext4 data structures book to Documentation/filesystems/ext4/ since the administrative information moved elsewhere. Signed-off-by: Darrick J. Wong <darrick.wong@oracle.com> Signed-off-by: Theodore Ts'o <tytso@mit.edu>
2018-10-06docs: move ext4 administrative docs to admin-guide/Darrick J. Wong1-0/+2
Move the ext4 mount option and other administrative stuff to the Linux administrator's guide. Signed-off-by: Darrick J. Wong <darrick.wong@oracle.com> Signed-off-by: Theodore Ts'o <tytso@mit.edu>
2018-10-03docs: generate a separate ext4 pdf file from the documentationDarrick J. Wong1-0/+2
The documentation build scripts won't build a pdf for the ext4 documentation unless explicitly called for, so ask for a separate ext4.pdf to be generated with all the documentation. Signed-off-by: Darrick J. Wong <darrick.wong@oracle.com> Signed-off-by: Theodore Ts'o <tytso@mit.edu>
2018-07-29ext4: import inode data fork chapter from wiki pageDarrick J. Wong1-1/+1
Import the chapter about inode data fork from the on-disk format wiki page into the kernel documentation. Signed-off-by: Darrick J. Wong <darrick.wong@oracle.com> Signed-off-by: Theodore Ts'o <tytso@mit.edu>
2017-12-12docs: Remove "could not extract kernel version" warningJonathan Corbet1-1/+0
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>
2017-09-08docs-rst: don't require adjustbox anymoreMauro Carvalho Chehab1-3/+0
Only the media PDF book was requiring adjustbox, in order to scale big tables. That worked pretty good with Sphinx versions 1.4 and 1.5, but Spinx 1.6 changed the way tables are produced, by introducing some weird macros before tabulary. That causes adjustbox to fail. So, it can't be used anymore, and its usage was removed from the media book. So, let's remove it from conf.py and sphinx-pre-install. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-09-08docs-rst: conf.py: only setup notice box colors if Sphinx < 1.6Mauro Carvalho Chehab1-19/+43
Sphinx 1.5 added a new way to change backward colors for note boxes, but kept backward compatibility with 1.4. On Sphinx 1.6, the old way stopped working, in favor of a new less hackish way. Unfortunately, this is currently too buggy to be used, and the old way doesn't work anymore. So, we have no option but to stick with boring notice boxes. One example of such bug is the notice that it is inside struct v4l2_plane, at the "bytesused" field. At least, add a notice about how to use, as maybe some day the bug will vanish. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-09-08docs-rst: conf.py: remove lscape from LaTeX preambleMauro Carvalho Chehab1-3/+0
Only the media book used this extension in the past, but it is not required anymore. Cleanup patch only. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-08-27docs-rst: fix verbatim font size on tablesMauro Carvalho Chehab1-1/+1
On Sphinx 1.6, fancy boxes are used for verbatim. The sphinx.sty sets verbatim font is always \small. That causes a problem inside tables that use smaller fonts, as it can be too big for the box. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-08-24docs: fix minimal sphinx version in conf.pyMarkus Heiser1-1/+1
according to what Documentation/doc-guide/sphinx.rst says:: The ReST markups currently used by the Documentation/ files are meant to be built with ``Sphinx`` version 1.3 or upper. Signed-off-by: Markus Heiser <markus.heiser@darmarit.de> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-08-24docs-rst: pdf: use same vertical margin on all Sphinx versionsMauro Carvalho Chehab1-1/+1
Currently, on Sphinx up to version 1.4, pdf output uses a vertical margin of 1 inch. For upper versions, it uses a margin of 0.5 inches. That causes both page headers and footers to be very close to the margin of the sheet. Not all printers support writing like that. Also, there's no reason why the layout for newer versions would be different than for previous ones. So, standardize it, by always setting to 1 inch. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-06-23Docs: Fix breakage with Sphinx 1.5 and upperMauro Carvalho Chehab1-2/+6
Commit 85c21e5c3ee7 (docs-rst: better adjust margins and font size) added a \usepackage{geometry} that conflicts with another inclusion deep within the dependencies with newer versions of Sphinx, causing the the PDF build to fail with a "conflicting parameters" error. Detect the Sphinx version, using sphinxsetup for Sphinx versions 1.5 and upper. Fixes: 85c21e5c3ee74fb75d690c57f7066bae7e2dca55 [jc: Tweaked logic to exclude 1.5.x for x < 3 ] Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
2017-06-23Docs: Include the Latex "ifthen" packageJonathan Corbet1-0/+1
Otherwise we get PDF build failures when LaTeX refused to acknowledge the existence of \ifthenelse Fixes: 41cff161fe99d1c6a773becc2250a1dc3ac035ff Cc: Mauro Carvalho Chehab <mchehab@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-05-16docs-rst: convert sh book to ReSTMauro Carvalho Chehab1-0/+2
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-16docs-rst: convert networking book to ReSTMauro Carvalho Chehab1-0/+2
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-16docs-rst: convert filesystems book to ReSTMauro Carvalho Chehab1-0/+2
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-16docs-rst: add userspace API book to pdf outputMauro Carvalho Chehab1-0/+2
The userspace API book was added without the bits required to generate PDF output. Add them. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
2017-05-16docs-rst: add sound book to pdf outputMauro Carvalho Chehab1-0/+2
The sound subsystem book was added without the bits required to generate PDF output. Add them. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
2017-05-16docs-rst: add dev-tools book to pdf outputMauro Carvalho Chehab1-0/+2
The dev-tools API book was added without the bits required to generate PDF output at the main conf.py. Add them. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
2017-05-16docs-rst: add crypto API book to pdf outputMauro Carvalho Chehab1-0/+2
The crypto API book was added without the bits required to generate PDF output. Add them. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
2017-05-16docs-rst: conf.py: remove kernel-documentation from LaTeXMauro Carvalho Chehab1-3/+1
There's no kernel-documentation.rst file at Documentation/ anymore. So, remove it from the list of LaTeX-generated documents. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
2017-05-16docs-rst: conf.py: sort LaTeX documents in alphabetical orderMauro Carvalho Chehab1-6/+7
As we add more documents, it makes more sense to sort the entries there in alphabetical order, as it makes easier to check if something is not there. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
2017-05-16conf.py: define a color for important markup on PDF outputMauro Carvalho Chehab1-1/+7
As kdbg.rst uses the ".. important::" annotation, let's define a color for PDF output. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
2017-05-16docs-rst: convert kernel-hacking to ReSTMauro Carvalho Chehab1-0/+2
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-03Merge branch 'for-linus' of ↵Linus Torvalds1-0/+2
git://git.kernel.org/pub/scm/linux/kernel/git/dtor/input Pull input subsystem updates from Dmitry Torokhov: - a big update from Mauro converting input documentation to ReST format - Synaptics PS/2 is now aware of SMBus companion devices, which means that we can now use native RMI4 protocol to handle touchpads, instead of relying on legacy PS/2 mode. - we removed support from BMA180 accelerometer from input devices as it is now handled properly by IIO - update to TSC2007 to corretcly report pressure - other miscellaneous driver fixes. * 'for-linus' of git://git.kernel.org/pub/scm/linux/kernel/git/dtor/input: (152 commits) Input: ar1021_i2c - use BIT to check for a bit Input: twl4030-pwrbutton - use input_set_capability() helper Input: twl4030-pwrbutton - use correct device for irq request Input: ar1021_i2c - enable touch mode during open Input: add uinput documentation dt-bindings: input: add bindings document for ar1021_i2c driver dt-bindings: input: rotary-encoder: fix typo Input: xen-kbdfront - add module parameter for setting resolution ARM: pxa/raumfeld: fix compile error in rotary controller resources Input: xpad - do not suggest writing to Dominic Input: xpad - don't use literal blocks inside footnotes Input: xpad - note that usb/devices is now at /sys/kernel/debug/ Input: docs - freshen up introduction Input: docs - split input docs into kernel- and user-facing Input: docs - note that MT-A protocol is obsolete Input: docs - update joystick documentation a bit Input: docs - remove disclaimer/GPL notice Input: fix "Game console" heading level in joystick documentation Input: rotary-encoder - remove references to platform data from docs Input: move documentation for Amiga CD32 ...
2017-04-06Input: create a book with Linux Input documentationMauro Carvalho Chehab1-0/+2
Now that all files under Documentation/input follows the ReST markup language, rename them to *.rst and create a book for the Linux Input subsystem. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Dmitry Torokhov <dmitry.torokhov@gmail.com>
2017-03-31Use sphinx.version_info directly instead of parsingRémy Léone1-2/+2
Using the development version of sphinx caused the parsing of the version to fail. Signed-off-by: Rémy Léone <remy.leone@gmail.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-03-09docs-rst: automatically convert Graphviz and SVG imagesMarkus Heiser1-1/+1
This patch brings scalable figure, image handling and a concept to embed *render* markups: * DOT (http://www.graphviz.org) * SVG For image handling use the 'image' replacement:: .. kernel-image:: svg_image.svg :alt: simple SVG image For figure handling use the 'figure' replacement:: .. kernel-figure:: svg_image.svg :alt: simple SVG image SVG image example Embed *render* markups (or languages) like Graphviz's **DOT** is provided by the *render* directive.:: .. kernel-render:: DOT :alt: foobar digraph :caption: Embedded **DOT** (Graphviz) code. digraph foo { "bar" -> "baz"; } The *render* directive is a concept to integrate *render* markups and languages, yet supported markups: * DOT: render embedded Graphviz's **DOT** * SVG: render embedded Scalable Vector Graphics (**SVG**) Cc: Jani Nikula <jani.nikula@linux.intel.com> Cc: Laurent Pinchart <laurent.pinchart@ideasonboard.com> Tested-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Tested-by: Daniel Vetter <daniel.vetter@ffwll.ch> Signed-off-by: Daniel Vetter <daniel.vetter@intel.com> (v2 - v5) Signed-off-by: Markus Heiser <markus.heiser@darmarit.de> (v1, v6) Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-03-04Documentation/sphinx: fix primary_domain configurationJohn Keeping1-1/+1
With Sphinx 1.5.3 I get the warning: WARNING: primary_domain 'C' not found, ignored. It seems that domain names in Sphinx are case-sensitive and for the C domain the name must be lower case. Signed-off-by: John Keeping <john@metanate.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-02-06docs: Remove the copyright year from conf.pyJonathan Corbet1-1/+1
It had gone stale, of course, as it would every year, a single date doesn't really cover things, and the date isn't really needed anyway.
2016-11-19docs-rst: doc-guide: split the kernel-documentation.rst contentsMauro Carvalho Chehab1-0/+2
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-17docs: Add more manuals to the PDF buildJonathan Corbet1-0/+6
There were a few manuals that weren't being built in PDF format, but there's no reason not to... Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-11-17docs-rst: fix LaTeX \DURole renewcommand with Sphinx 1.3+Mauro Carvalho Chehab1-1/+5
PDF build on Kernel 4.9-rc? returns an error with Sphinx 1.3.x and Sphinx 1.4.x, when trying to solve some cross-references. The solution is to redefine the \DURole macro. However, this is redefined too late. Move such redefinition to LaTeX preamble and bind it to just the Sphinx versions where the error is known to be present. Tested by building the documentation on interactive mode: make PDFLATEX=xelatex -C Documentation/output/./latex Fixes: e61a39baf74d ("[media] index.rst: Fix LaTeX error in interactive mode on Sphinx 1.4.x") Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-11-03Documentation/sphinx: set literal block highlight language to noneJani Nikula1-1/+1
Set the default highlight language to "none", i.e. do not try to guess the language and do automatic syntax highlighting on literal blocks. Eyeballing around the generated documentation, we don't seem to actually have a lot of literal blocks that would benefit from syntax highlighting. The C code blocks we do have are typically very short, and most of the literal blocks are things that shouldn't be highlighted (or, do not have a pygments lexer). This seems to be true for literal blocks both in the rst source files and in source code comments. Not highlighting code is never wrong, but guessing the language wrong almost invariably leads to silly or confusing highlighting. At the time of writing, admin-guide/oops-tracing.rst and admin-guide/ramoops.rst contain good examples of 1) a small C code snippet not highlighted, 2) a hex dump highligted as who knows what, 3) device tree block highlighted as C or maybe Python, 4) a terminal interaction highlighted as code in some language, and finally, 5) some C code snippets correctly identified as C. I think we're better off disabling language guessing, and going by explicitly identified languages for longer code blocks. It is still possible to enable highlighting on an rst source file basis using the highlight directive: .. higlight:: language and on a literal block basis using the code-block directive: .. code-block:: language See http://www.sphinx-doc.org/en/latest/markup/code.html for details. Cc: Jonathan Corbet <corbet@lwn.net> Cc: Mauro Carvalho Chehab <mchehab@osg.samsung.com> Cc: Markus Heiser <markus.heiser@darmarit.de> Signed-off-by: Jani Nikula <jani.nikula@intel.com>
2016-11-03Documentation/sphinx: include admin-guide in the latex/pdf buildJani Nikula1-1/+1
Fix the warning: WARNING: "latex_documents" config value references unknown document user/index Reviewed-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jani Nikula <jani.nikula@intel.com>
2016-10-24docs-rst: create an user's manual bookMauro Carvalho Chehab1-0/+2
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-10-24docs: rename development-process/ to process/Mauro Carvalho Chehab1-1/+1
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>