summaryrefslogtreecommitdiffstats
path: root/Documentation/doc-guide
Commit message (Collapse)AuthorAgeFilesLines
* scripts: kernel-doc: parse next structs/unionsMauro Carvalho Chehab2017-12-211-0/+46
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | There are several places within the Kernel tree with nested structs/unions, like this one: struct ingenic_cgu_clk_info { const char *name; enum { CGU_CLK_NONE = 0, CGU_CLK_EXT = BIT(0), CGU_CLK_PLL = BIT(1), CGU_CLK_GATE = BIT(2), CGU_CLK_MUX = BIT(3), CGU_CLK_MUX_GLITCHFREE = BIT(4), CGU_CLK_DIV = BIT(5), CGU_CLK_FIXDIV = BIT(6), CGU_CLK_CUSTOM = BIT(7), } type; int parents[4]; union { struct ingenic_cgu_pll_info pll; struct { struct ingenic_cgu_gate_info gate; struct ingenic_cgu_mux_info mux; struct ingenic_cgu_div_info div; struct ingenic_cgu_fixdiv_info fixdiv; }; struct ingenic_cgu_custom_info custom; }; }; Currently, such struct is documented as: **Definition** :: struct ingenic_cgu_clk_info { const char * name; }; **Members** ``name`` name of the clock With is obvioulsy wrong. It also generates an error: drivers/clk/ingenic/cgu.h:169: warning: No description found for parameter 'enum' However, there's nothing wrong with this kernel-doc markup: everything is documented there. It makes sense to document all fields there. So, add a way for the core to parse those structs. With this patch, all documented fields will properly generate documentation. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* docs: kernel-doc.rst: add documentation about man pagesMauro Carvalho Chehab2017-12-211-0/+34
| | | | | | | | | kernel-doc-nano-HOWTO.txt has a chapter about man pages production. While we don't have a working "make manpages" target, add it. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* docs: kernel-doc.rst: improve typedef documentationMauro Carvalho Chehab2017-12-211-10/+22
| | | | | | | | Add documentation about typedefs for function prototypes and move it to happen earlier. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* docs: kernel-doc.rst: improve structs chapterMauro Carvalho Chehab2017-12-211-24/+24
| | | | | | | | | | | There is a mess on this chapter: it suggests that even enums and unions should be documented with "struct". That's not the way it should be ;-) Fix it and move it to happen earlier. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* docs: kernel-doc.rst: improve function documentation sectionMauro Carvalho Chehab2017-12-211-39/+61
| | | | | | | | | Move its contents to happen earlier and improve the description of return values, adding a subsection to it. Most of the contents there came from kernel-doc-nano-HOWTO.txt. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* docs: kernel-doc.rst: improve private members descriptionMauro Carvalho Chehab2017-12-211-26/+30
| | | | | | | | | The private members section can now be moved to be together with the arguments section. Move it there and add an example about the usage of public: Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* docs: kernel-doc.rst: better describe kernel-doc argumentsMauro Carvalho Chehab2017-12-211-3/+41
| | | | | | | | | Add a new section to describe kernel-doc arguments, adding examples about how identation should happen, as failing to do that causes Sphinx to do the wrong thing. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* Documentation: fix ref to sphinx/kerneldoc.pyTom Saeger2017-10-191-1/+1
| | | | | Signed-off-by: Tom Saeger <tom.saeger@oracle.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* sphinx.rst: Allow Sphinx version 1.6 at the docsMauro Carvalho Chehab2017-08-261-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>
* sphinx.rst: document scripts/sphinx-pre-install scriptMauro Carvalho Chehab2017-07-231-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>
* sphinx.rst: better organize the documentation about PDF buildMauro Carvalho Chehab2017-07-171-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>
* sphinx.rst: describe the install requirements for kfigureMauro Carvalho Chehab2017-07-171-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>
* sphinx.rst: fix unknown referenceMauro Carvalho Chehab2017-07-171-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>
* sphinx.rst: explain the usage of virtual environmentMauro Carvalho Chehab2017-07-171-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>
* docs-rst: move Sphinx install instructions to sphinx.rstMauro Carvalho Chehab2017-07-171-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>
* kernel-doc: describe the ``literal`` syntaxMauro Carvalho Chehab2017-05-161-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>
* docs: update old references for DocBook from the documentationMauro Carvalho Chehab2017-05-162-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>
* docs: remove DocBook from the building systemMauro Carvalho Chehab2017-05-161-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>
* docs-rst: automatically convert Graphviz and SVG imagesMarkus Heiser2017-03-093-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>
* doc: Explain light-handed markup preference a bit betterDaniel Vetter2017-03-091-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>
* docs-rst: parse-headers.pl: cleanup the documentationMauro Carvalho Chehab2016-11-301-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>
* Merge branch 'mauro-doc' into docs-nextJonathan Corbet2016-11-191-1/+6
|
* parse-headers.rst: add an introduction to the man pageMauro Carvalho Chehab2016-11-191-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>
* parse-headers.pl: add documentation for this scriptMauro Carvalho Chehab2016-11-192-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>
* docs-rst: doc-guide: split the kernel-documentation.rst contentsMauro Carvalho Chehab2016-11-195-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>
OpenPOWER on IntegriCloud