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 -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
