On Sat, Jun 04, 2016 at 02:37:01PM +0300, Jani Nikula wrote: > 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. dogfooding = our autobuilder also already eats it: https://01.org/linuxgraphics/gfx-docs/drm/ > 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. I've read through all the patches and things look good. Now my python/perl/sphinx fu is by far not good enough for a full review, hence just: Acked-by: Daniel Vetter <daniel.vetter@xxxxxxxx> It also works really nicely, we already started to land some kernel-doc markup fixup patches for drm. Tested-by: Daniel Vetter <daniel.vetter@xxxxxxxx> I really think this is awesome, and it's a good foundation for more polish in the toolchain on top (like Markus' improved tables, or some of the ideas floating around about better linting for kernel-doc). But right now I think the next step is to convert a pile of docs and gain some real-world experience with the tool-chain. > 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. Please send me a pull request with the tag to merge into drm-misc. > I plan to update Documentation/kernel-doc-nano-HOWTO.txt for Sphinx and > rst, obviously converting it to rst while at it. Cheers, Daniel > > 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 > -- Daniel Vetter Software Engineer, Intel Corporation http://blog.ffwll.ch -- 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
