linux-toradex.git/Documentation/sphinx, branch v4.10

docs: sphinx-extensions: make rstFlatTable work with docutils 0.13

2016-12-18T20:30:29+00:00

In docutils 0.13, the return type of get_column_widths method of the
Table directive has changed [1], which breaks our flat-table directive
and leads to a TypeError when trying to build the docs [2].

This patch adds support for the new return type, while keeping support
for older docutils versions too.

[1] https://sourceforge.net/p/docutils/patches/120/
[2] https://sourceforge.net/p/docutils/bugs/303/

Signed-off-by: Dmitry Shachnev 
Cc:  # 4.8.x-
Signed-off-by: Jonathan Corbet

docs-rst: parse-headers.pl: cleanup the documentation

2016-12-01T00:08:09+00:00

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 
Signed-off-by: Jonathan Corbet

parse-headers.pl: add documentation for this script

2016-11-19T17:22:08+00:00

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 
Signed-off-by: Jonathan Corbet

Documentation/sphinx: rename kernel-doc.py to kerneldoc.py

2016-10-19T22:02:00+00:00

Python module names should not have hyphens per [PEP 8]. Drop the hyphen
from kernel-doc.py. The extension directive remains unchanged.

[PEP 8] https://www.python.org/dev/peps/pep-0008/#package-and-module-names

Reported-by: Markus Heiser 
Signed-off-by: Jani Nikula 
Signed-off-by: Jonathan Corbet

Merge tag 'docs-next' of git://git.lwn.net/linux.git into patchwork

2016-09-19T19:36:41+00:00

Merge back from docs-next in order to get the cdomain extension.

With such extension, the number of warnings when building docs
in nitpick mode reduced from 22 to 2 warnings.

* docs-next/docs-next:
  docs/driver-model: fix typo
  DMA-API-HOWTO:  is no more
  doc-rst:c-domain: function-like macros arguments
  doc-rst:c-domain: fix sphinx version incompatibility
  Documentation/filesystems: Fixed typo
  docs: Don't format internal MPT docs
  docs: split up serial-interfaces.rst
  docs: Pull the HSI documentation together
  docs: Special-case function-pointer parameters in kernel-doc
  docs: make kernel-doc handle varargs properly
  x86: fix memory ranges in mm documentation
  documentation/scsi: Remove nodisconnect parameter
  doc: ioctl: Add some clarifications to botching-up-ioctls
  docs: split up the driver book
  Docs: sphinxify device-drivers.tmpl

doc-rst:c-domain: function-like macros arguments

2016-09-16T15:53:40+00:00

Handle signatures of function-like macros well. Don't try to deduce
arguments types of function-like macros.

Signed-off-by: Markus Heiser 
Signed-off-by: Jonathan Corbet

doc-rst:c-domain: fix sphinx version incompatibility

2016-09-16T15:53:23+00:00

The self.indexnode's tuple has changed in sphinx version 1.4, from a
former 4 element tuple to a 5 element tuple.

https://github.com/sphinx-doc/sphinx/commit/e6a5a3a92e938fcd75866b4227db9e0524d58f7c

Signed-off-by: Markus Heiser 
Signed-off-by: Jonathan Corbet

[media] docs-rst: parse-headers.pl: use the C domain for cross-references

2016-09-09T12:20:27+00:00

Instead of keep using the normal reference, move to the C
domain ones. Using C domains everywhere will allow
cross-references between kAPI and uAPI docs.

Acked-by: Jonathan Corbet 
Signed-off-by: Mauro Carvalho Chehab

[media] docs-rst: parse-headers.pl: make debug a command line option

2016-09-09T12:20:06+00:00

Add a parser for the --debug option, in order to allow
seeing what the parser is doing.

Acked-by: Jonathan Corbet 
Signed-off-by: Mauro Carvalho Chehab

docs: sphinx-extensions: add metadata parallel-safe

2016-09-01T14:19:02+00:00

The setup() function of a Sphinx-extension can return a dictionary. This
is treated by Sphinx as metadata of the extension [1].

With metadata "parallel_read_safe = True" a extension is marked as
save for "parallel reading of source". This is needed if you want
build in parallel with N processes. E.g.:

  make SPHINXOPTS=-j4 htmldocs

will no longer log warnings like:

  WARNING: the foobar extension does not declare if it is safe for
  parallel reading, assuming it isn't - please ask the extension author
  to check and make it explicit.

Add metadata to extensions:

* kernel-doc
* flat-table
* kernel-include

[1] http://www.sphinx-doc.org/en/stable/extdev/#extension-metadata

Signed-off-by: Markus Heiser 
Tested-by: Mauro Carvalho Chehab 
Signed-off-by: Jonathan Corbet