Re: [PATCH v2 00/38] Documentation/sphinx

[Daniel Vetter <daniel@ffwll.ch>]

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@ffwll.ch>

It also works really nicely, we already started to land some kernel-doc
markup fixup patches for drm.

Tested-by: Daniel Vetter <daniel.vetter@ffwll.ch>

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@intel.com
> [2] http://mid.gmane.org/877fec7gfm.fsf@intel.com
> 
> 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