[PATCH v2 00/38] Documentation/sphinx

From: Jani Nikula
Date: Sat Jun 04 2016 - 07:38:46 EST

Jon, this is v2 of [1] and [2], with a considerable amount of polish and
fixes added. We started dogfooding this within drm-intel, and Daniel has
reviewed the lot and contributed a number of fixes, most notably
accurate file and line number references from Sphinx build
errors/warnings to the kernel-doc comments in source code.

We believe this is now in good shape for merging for v4.8. It's all in
my sphinx-for-docs-next branch that you've already looked at; pull
details below.

When this lands in docs-next and we can backmerge to drm, we'll plunge
ahead and convert gpu.tmpl to rst, and have that ready for v4.8. We
think it's best to contribute that via the drm tree, as it'll involve
splitting up the documentation and likely numerous updates to kernel-doc

I plan to update Documentation/kernel-doc-nano-HOWTO.txt for Sphinx and
rst, obviously converting it to rst while at it.


[1] http://mid.gmane.org/cover.1463748027.git.jani.nikula@xxxxxxxxx
[2] http://mid.gmane.org/877fec7gfm.fsf@xxxxxxxxx

The following changes since commit 1a695a905c18548062509178b98bc91e67510864:

Linux 4.7-rc1 (2016-05-29 09:29:24 -0700)

are available in the git repository at:

git://people.freedesktop.org/~jani/drm sphinx-for-docs-next

for you to fetch changes up to d90368f2fa7ded7c56d214aef087e88bba5199e7:

doc/sphinx: Track line-number of starting blocks (2016-06-04 11:35:59 +0300)

Daniel Vetter (6):
doc/sphinx: Pass right filename as source
scripts/kernel-doc: Remove duplicated DOC: start handling
doc/sphinx: Stop touching state_machine internals
scripts/kernel-doc: Also give functions symbolic names
scripts/kernel-doc: Add option to inject line numbers
doc/sphinx: Track line-number of starting blocks

Jani Nikula (31):
kernel-doc/rst: fix use of uninitialized value
kernel-doc: support printing exported and non-exported symbols
Documentation/sphinx: add basic working Sphinx configuration and build
Documentation: add .gitignore
Documentation/sphinx: add Sphinx kernel-doc directive extension
Documentation/sphinx: configure the kernel-doc extension
Documentation/sphinx: set version and release properly
sphinx: update docbook->rst conversion script match C domain spec
Documentation/sphinx: nicer referencing of struct in docbook->rst conversion
kernel-doc: add names for states and substates
kernel-doc: add names for output selection
kernel-doc/rst: do not output DOC: section titles for requested ones
kernel-doc/rst: reference functions according to C domain spec
kernel-doc/rst: &foo references are more universal than structs
kernel-doc/rst: add support for &union foo and &typedef foo references
kernel-doc/rst: add support for struct/union/enum member references
kernel-doc/rst: drop redundant unescape in highlighting
kernel-doc/rst: highlight function/struct/enum purpose lines too
kernel-doc: do not regard $, %, or & prefixes as special in section names
kernel-doc: fix wrong code indentation
kernel-doc/rst: blank lines in output are not needed
kernel-doc: strip leading blank lines from inline doc comments
kernel-doc/rst: change the output layout
kernel-doc: improve handling of whitespace on the first line param description
kernel-doc: strip leading whitespace from continued param descs
kernel-doc/rst: use *undescribed* instead of _undescribed_
kernel-doc/rst: remove fixme comment
kernel-doc: limit the "section header:" detection to a select few
kernel-doc: concatenate contents of colliding sections
kernel-doc: reset contents and section harder
Documentation/sphinx: fix kernel-doc extension on python3

Jonathan Corbet (1):
sphinx: cheesy script to convert .tmpl files

Documentation/.gitignore | 1 +
Documentation/DocBook/Makefile | 7 +-
Documentation/Makefile.sphinx | 63 +++++
Documentation/conf.py | 414 ++++++++++++++++++++++++++++++
Documentation/index.rst | 23 ++
Documentation/sphinx/convert_template.sed | 18 ++
Documentation/sphinx/kernel-doc.py | 127 +++++++++
Documentation/sphinx/post_convert.sed | 23 ++
Documentation/sphinx/tmplcvt | 19 ++
Makefile | 5 +-
scripts/kernel-doc | 392 ++++++++++++++++++----------
11 files changed, 948 insertions(+), 144 deletions(-)
create mode 100644 Documentation/.gitignore
create mode 100644 Documentation/Makefile.sphinx
create mode 100644 Documentation/conf.py
create mode 100644 Documentation/index.rst
create mode 100644 Documentation/sphinx/convert_template.sed
create mode 100644 Documentation/sphinx/kernel-doc.py
create mode 100644 Documentation/sphinx/post_convert.sed
create mode 100755 Documentation/sphinx/tmplcvt