linux.git/Documentation/sphinx/parse-headers.pl, branch v4.14

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

[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-rst: parse-heraders.pl: escape LaTeX characters

2016-08-18T22:42:07+00:00

Let's escape the LaTeX characters, to avoid troubles when
outputing them.

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

doc-rst: parse-headers: remove trailing spaces

2016-07-09T12:42:31+00:00

The function that replace references add a "\ " at the end of
references, to avoid the ReST markup parser to not identify
them as references. That works fine except for the end of lines,
as a sequence of { '\', ' ', '\n' } characters makes Sphinx
to ignore the end of line. So, strip those escape/spaces at the
end of lines.

Signed-off-by: Mauro Carvalho Chehab

doc-rst: parse-headers: don't do substituition references

2016-07-07T18:13:17+00:00

Add one extra escape character to avoid those warnings:
	Documentation/linux_tv/videodev2.h.rst:6: WARNING: Inline substitution_reference start-string without end-string.

Signed-off-by: Mauro Carvalho Chehab

doc-rst: parse-headers: add an option to ignore enum symbols

2016-07-07T18:13:07+00:00

At videodev2.h, we have hundreds of symbols that don't
currently have a reference yet. Let's ignore for how, while
we don't improve those cross-refs.

Signed-off-by: Mauro Carvalho Chehab

doc-rst: parse-headers: better handle comments at the source code

2016-07-07T18:12:48+00:00

We should not let comments to mangle with the symbols
parsing. Unfortunately, videodev2.h has lots of those
in the middle of enums and structs. So, we need to improve
our parser to discard them.

Signed-off-by: Mauro Carvalho Chehab

doc-rst: parse-headers: fix multiline typedef handler

2016-07-07T11:12:57+00:00

The typedef handler should do two things to be generic:
  1) parse typedef enums;
  2) accept both possible syntaxes:
	 typedef struct foo { .. } foo_t;
	 typedef struct { .. } foo_t;

Unfortunately, this is needed to parse some legacy DVB
files, like dvb/audio.h.

Signed-off-by: Mauro Carvalho Chehab