summaryrefslogtreecommitdiff
path: root/Documentation/doc-guide
AgeCommit message (Collapse)AuthorFilesLines
2017-08-27sphinx.rst: Allow Sphinx version 1.6 at the docsMauro Carvalho Chehab1-3/+1
Now that the PDF building issues with Sphinx 1.6 got fixed, update the documentation and scripts accordingly. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-07-24sphinx.rst: document scripts/sphinx-pre-install scriptMauro Carvalho Chehab1-4/+44
Now that we have a script to check for Sphinx dependencies, document it. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-07-17sphinx.rst: better organize the documentation about PDF buildMauro Carvalho Chehab1-8/+13
Instead of having it on just one note, add a separate section. This way, we could later improve it, providing a better guide about the needed steps for PDF builds. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-07-17sphinx.rst: describe the install requirements for kfigureMauro Carvalho Chehab1-0/+13
As we now have a document describing the install requirements for Sphinx, add there the need for GraphViz and ImageMagick. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-07-17sphinx.rst: fix unknown referenceMauro Carvalho Chehab1-1/+1
There's no "Sphinx C Domain" reference at the Kernel documentation. So, don't use references for it. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-07-17sphinx.rst: explain the usage of virtual environmentMauro Carvalho Chehab1-0/+32
As the Sphinx build seems very fragile, specially for PDF output, add a notice about how to use it on a virtual environment. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-07-17docs-rst: move Sphinx install instructions to sphinx.rstMauro Carvalho Chehab1-0/+17
The toolchain used by Sphinx is somewhat complex, and installing it should be part of the doc-guide. Move it out of changes.rst. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-05-16kernel-doc: describe the ``literal`` syntaxMauro Carvalho Chehab1-0/+10
changeset b97f193abf83 ("scripts/kernel-doc: fix parser for apostrophes") added support for ``literal`` inside kernel-doc, in order to allow using the "%" symbol inside a literal block, as this is used at printk() description. Document it. Fixes: b97f193abf83 ("scripts/kernel-doc: fix parser for apostrophes") Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
2017-05-16docs: update old references for DocBook from the documentationMauro Carvalho Chehab2-6/+0
DocBook is mentioned several times at the documentation. Update the obsolete references from it at the DocBook. Acked-by: SeongJae Park <sj38.park@gmail.com> Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
2017-05-16docs: remove DocBook from the building systemMauro Carvalho Chehab1-90/+0
Now that we don't have any DocBook anymore, remove it from the building system. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
2017-03-09docs-rst: automatically convert Graphviz and SVG imagesMarkus Heiser3-2/+109
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-09doc: Explain light-handed markup preference a bit betterDaniel Vetter1-1/+16
We're still pretty far away from anything like a consensus, but there's clearly a lot of people who prefer an as-light as possible approach to converting existing .txt files to .rst. Make sure this is properly taken into account and clear. Motivated by discussions with Peter and Christoph and others. Cc: Christoph Hellwig <hch@infradead.org> Cc: Peter Zijlstra <peterz@infradead.org> Cc: Jani Nikula <jani.nikula@linux.intel.com> Cc: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Daniel Vetter <daniel.vetter@intel.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-12-01docs-rst: parse-headers.pl: cleanup the documentationMauro Carvalho Chehab1-19/+3
Keeping both rst and in-file documentation in sync can be harsh. So, simplify the script's internal documntation to a bare minimum, and add a mention to the ReST file with its full documentation. This way, a quick help is still available at the command line, while the complete one is maintained at the ReST format. As we won't be using pad2rst anymore, do a cleanup at the ReST file. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-11-19Merge branch 'mauro-doc' into docs-nextJonathan Corbet6-0/+915
2016-11-19parse-headers.rst: add an introduction to the man pageMauro Carvalho Chehab1-2/+24
The pod2rst tool generated a man page for parse-headers.pl script, but it is better to put it into some context. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-11-19parse-headers.pl: add documentation for this scriptMauro Carvalho Chehab2-0/+187
Provide a man page for parse-headers.pl, describing how to use it. The documentation on ReST format was generated via pod2rst: http://search.cpan.org/~dowens/Pod-POM-View-Restructured-0.02/bin/pod2rst Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-11-19docs-rst: doc-guide: split the kernel-documentation.rst contentsMauro Carvalho Chehab5-0/+701
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>