Re: [PATCH v2 00/38] Documentation/sphinx
From: Daniel Vetter
Date: Sat Jun 04 2016 - 08:15:32 EST
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