[PATCH v2 00/38] Documentation/sphinx

[Jani Nikula]

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
comments.

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

BR,
Jani.



[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

-- 
2.1.4