Hi Jon,
Sorry for resending this big series. The content is almost identical
to the first version, but this one can be applied directly on the top
of docs/next, without requiring the sphinx-build-wrapper series.
I'm opting for this approach, in order to avoid adding 42 lines to
sphinx-build-wrapper just to be removed at the v1 of this series.
-
The goal of this series is to drop one of the most ancient and ugliest
hack from the documentation build system. Before migrating to Sphinx,
the media subsystem already had a very comprehensive uAPI book, together
with a build time system to detect and point for any documentation gaps.
When migrating to Sphinx, we ported the logic to a Perl script
(parse-headers.pl) and Markus came up with a Sphinx extension
(kernel_include.py). We also added some files to control how parse-headers
produce results, and a Makefile.
At the initial Sphinx versions (1.4.1 if I recall correctly), when
a new symbol is added to videodev2.h, a new warning were
produced at documentatiion time, it the patchset didn't have
the corresponding documentation path.
While kernel-include is generic, the only user at the moment is the media
subsystem.
This series gets rid of the Python script, replacing it by a command
line script and a class. The parse header class can optionally be used by
kernel-include to produce an enriched code that will contain cross-references.
As the other conversions, it starts with a bug-compatible version of
parse-headers, but the subsequent patches add more functionalities and
fix bugs.
It should be noticed that modern of Sphinx disabled the cross-reference
warnings. So, at the next series, I'll be re-adding it in a controlled way
(e.g. just for the references from kernel-include that has an special
argument).
The script also supports now generating a "toc" output, which will be used
at the next series.
-
v2:
- makes it indepentent of sphinx-build-wrapper patch series.
Mauro Carvalho Chehab (24):
docs: parse-headers.pl: improve its debug output format
docs: parse-headers.py: convert parse-headers.pl
docs: parse-headers.py: improve --help logic
docs: parse-headers.py: better handle @var arguments
docs: parse-headers.py: simplify the rules for hashes
tools: docs: parse-headers.py: move it from sphinx dir
tools: docs: parse_data_structs.py: add methods to return output
MAINTAINERS: add files from tools/docs to documentation entry
docs: uapi: media: Makefile: use parse-headers.py
docs: kernel_include.py: Update its coding style
docs: kernel_include.py: allow cross-reference generation
docs: kernel_include.py: generate warnings for broken refs
docs: kernel_include.py: move rawtext logic to separate functions
docs: kernel_include.py: move range logic to a separate function
docs: kernel_include.py: remove range restriction for gen docs
docs: kernel_include.py: move code and literal functions
docs: kernel_include.py: add support to generate a TOC table
docs: kernel_include.py: append line numbers to better report errors
docs: kernel_include.py: move apply_range() and add a docstring
docs: kernel_include.py: remove line numbers from parsed-literal
docs: kernel_include.py: remove Include class inheritance
docs: kernel_include.py: document all supported parameters
scripts: sphinx-build-wrapper: get rid of uapi/media Makefile
docs: sphinx: drop parse-headers.pl
.pylintrc | 2 +-
Documentation/Makefile | 3 +-
Documentation/sphinx/kernel_include.py | 519 +++++++++----
Documentation/sphinx/parse-headers.pl | 404 ----------
Documentation/userspace-api/media/Makefile | 64 --
.../userspace-api/media/cec/cec-header.rst | 5 +-
.../media/{ => cec}/cec.h.rst.exceptions | 0
.../media/{ => dvb}/ca.h.rst.exceptions | 0
.../media/{ => dvb}/dmx.h.rst.exceptions | 0
.../media/{ => dvb}/frontend.h.rst.exceptions | 0
.../userspace-api/media/dvb/headers.rst | 17 +-
.../media/{ => dvb}/net.h.rst.exceptions | 0
.../media/mediactl/media-header.rst | 5 +-
.../{ => mediactl}/media.h.rst.exceptions | 0
.../userspace-api/media/rc/lirc-header.rst | 4 +-
.../media/{ => rc}/lirc.h.rst.exceptions | 0
.../userspace-api/media/v4l/videodev.rst | 4 +-
.../{ => v4l}/videodev2.h.rst.exceptions | 0
MAINTAINERS | 1 +
scripts/sphinx-build-wrapper | 719 ++++++++++++++++++
tools/docs/lib/__init__.py | 0
tools/docs/lib/enrich_formatter.py | 70 ++
tools/docs/lib/parse_data_structs.py | 452 +++++++++++
tools/docs/parse-headers.py | 60 ++
24 files changed, 1704 insertions(+), 625 deletions(-)
delete mode 100755 Documentation/sphinx/parse-headers.pl
delete mode 100644 Documentation/userspace-api/media/Makefile
rename Documentation/userspace-api/media/{ => cec}/cec.h.rst.exceptions (100%)
rename Documentation/userspace-api/media/{ => dvb}/ca.h.rst.exceptions (100%)
rename Documentation/userspace-api/media/{ => dvb}/dmx.h.rst.exceptions (100%)
rename Documentation/userspace-api/media/{ => dvb}/frontend.h.rst.exceptions (100%)
rename Documentation/userspace-api/media/{ => dvb}/net.h.rst.exceptions (100%)
rename Documentation/userspace-api/media/{ => mediactl}/media.h.rst.exceptions (100%)
rename Documentation/userspace-api/media/{ => rc}/lirc.h.rst.exceptions (100%)
rename Documentation/userspace-api/media/{ => v4l}/videodev2.h.rst.exceptions (100%)
create mode 100755 scripts/sphinx-build-wrapper
create mode 100644 tools/docs/lib/__init__.py
create mode 100644 tools/docs/lib/enrich_formatter.py
create mode 100755 tools/docs/lib/parse_data_structs.py
create mode 100755 tools/docs/parse-headers.py
--
2.50.1
