Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > linux.kernel > #1413744

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

From Daniel Vetter <daniel@ffwll.ch>
Newsgroups linux.kernel
Subject Re: [PATCH v2 00/38] Documentation/sphinx
Date 2016-06-04 14:20 +0200
Message-ID <rGiIx-we-1@gated-at.bofh.it> (permalink)
References <rGi5P-8on-3@gated-at.bofh.it>
Organization linux.* mail to news gateway

Show all headers | View raw

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

Back to linux.kernel | Previous | Next — Previous in thread | Next in thread | Find similar | Unroll thread

Thread

[PATCH v2 00/38] Documentation/sphinx Jani Nikula <jani.nikula@intel.com> - 2016-06-04 13:40 +0200
  [PATCH v2 10/38] Documentation/sphinx: nicer referencing of struct in docbook->rst conversion Jani Nikula <jani.nikula@intel.com> - 2016-06-04 13:40 +0200
  [PATCH v2 01/38] kernel-doc/rst: fix use of uninitialized value Jani Nikula <jani.nikula@intel.com> - 2016-06-04 13:40 +0200
  [PATCH v2 13/38] kernel-doc/rst: do not output DOC: section titles for requested ones Jani Nikula <jani.nikula@intel.com> - 2016-06-04 13:40 +0200
  [PATCH v2 14/38] kernel-doc/rst: reference functions according to C domain spec Jani Nikula <jani.nikula@intel.com> - 2016-06-04 13:40 +0200
  [PATCH v2 08/38] sphinx: cheesy script to convert .tmpl files Jani Nikula <jani.nikula@intel.com> - 2016-06-04 13:40 +0200
  [PATCH v2 02/38] kernel-doc: support printing exported and non-exported symbols Jani Nikula <jani.nikula@intel.com> - 2016-06-04 13:40 +0200
  [PATCH v2 12/38] kernel-doc: add names for output selection Jani Nikula <jani.nikula@intel.com> - 2016-06-04 13:40 +0200
  [PATCH v2 15/38] kernel-doc/rst: &foo references are more universal than structs Jani Nikula <jani.nikula@intel.com> - 2016-06-04 13:40 +0200
  [PATCH v2 05/38] Documentation/sphinx: add Sphinx kernel-doc directive extension Jani Nikula <jani.nikula@intel.com> - 2016-06-04 13:40 +0200
  [PATCH v2 03/38] Documentation/sphinx: add basic working Sphinx configuration and build Jani Nikula <jani.nikula@intel.com> - 2016-06-04 13:40 +0200
  [PATCH v2 28/38] kernel-doc/rst: remove fixme comment Jani Nikula <jani.nikula@intel.com> - 2016-06-04 13:50 +0200
  [PATCH v2 24/38] kernel-doc/rst: change the output layout Jani Nikula <jani.nikula@intel.com> - 2016-06-04 13:50 +0200
  [PATCH v2 22/38] kernel-doc/rst: blank lines in output are not needed Jani Nikula <jani.nikula@intel.com> - 2016-06-04 13:50 +0200
  [PATCH v2 37/38] scripts/kernel-doc: Add option to inject line numbers Jani Nikula <jani.nikula@intel.com> - 2016-06-04 13:50 +0200
  [PATCH v2 07/38] Documentation/sphinx: set version and release properly Jani Nikula <jani.nikula@intel.com> - 2016-06-04 13:50 +0200
  [PATCH v2 32/38] Documentation/sphinx: fix kernel-doc extension on python3 Jani Nikula <jani.nikula@intel.com> - 2016-06-04 13:50 +0200
  [PATCH v2 06/38] Documentation/sphinx: configure the kernel-doc extension Jani Nikula <jani.nikula@intel.com> - 2016-06-04 13:50 +0200
  [PATCH v2 20/38] kernel-doc: do not regard $, %, or & prefixes as special in section names Jani Nikula <jani.nikula@intel.com> - 2016-06-04 13:50 +0200
  [PATCH v2 19/38] kernel-doc/rst: highlight function/struct/enum purpose lines too Jani Nikula <jani.nikula@intel.com> - 2016-06-04 13:50 +0200
  [PATCH v2 23/38] kernel-doc: strip leading blank lines from inline doc comments Jani Nikula <jani.nikula@intel.com> - 2016-06-04 13:50 +0200
  [PATCH v2 26/38] kernel-doc: strip leading whitespace from continued param descs Jani Nikula <jani.nikula@intel.com> - 2016-06-04 13:50 +0200
  [PATCH v2 38/38] doc/sphinx: Track line-number of starting blocks Jani Nikula <jani.nikula@intel.com> - 2016-06-04 13:50 +0200
  [PATCH v2 17/38] kernel-doc/rst: add support for struct/union/enum member references Jani Nikula <jani.nikula@intel.com> - 2016-06-04 13:50 +0200
  [PATCH v2 31/38] kernel-doc: reset contents and section harder Jani Nikula <jani.nikula@intel.com> - 2016-06-04 13:50 +0200
  [PATCH v2 30/38] kernel-doc: concatenate contents of colliding sections Jani Nikula <jani.nikula@intel.com> - 2016-06-04 13:50 +0200
  [PATCH v2 29/38] kernel-doc: limit the "section header:" detection to a select few Jani Nikula <jani.nikula@intel.com> - 2016-06-04 13:50 +0200
    Re: [PATCH v2 29/38] kernel-doc: limit the "section header:"  detection to a select few Jonathan Corbet <corbet@lwn.net> - 2016-06-09 17:10 +0200
      Re: [PATCH v2 29/38] kernel-doc: limit the "section header:" detection to a select few Jani Nikula <jani.nikula@intel.com> - 2016-06-09 18:50 +0200
  [PATCH v2 36/38] scripts/kernel-doc: Also give functions symbolic names Jani Nikula <jani.nikula@intel.com> - 2016-06-04 13:50 +0200
  [PATCH v2 21/38] kernel-doc: fix wrong code indentation Jani Nikula <jani.nikula@intel.com> - 2016-06-04 13:50 +0200
  [PATCH v2 34/38] scripts/kernel-doc: Remove duplicated DOC: start handling Jani Nikula <jani.nikula@intel.com> - 2016-06-04 13:50 +0200
  [PATCH v2 18/38] kernel-doc/rst: drop redundant unescape in highlighting Jani Nikula <jani.nikula@intel.com> - 2016-06-04 13:50 +0200
  [PATCH v2 33/38] doc/sphinx: Pass right filename as source Jani Nikula <jani.nikula@intel.com> - 2016-06-04 13:50 +0200
  [PATCH v2 16/38] kernel-doc/rst: add support for &union foo and &typedef foo references Jani Nikula <jani.nikula@intel.com> - 2016-06-04 13:50 +0200
  [PATCH v2 25/38] kernel-doc: improve handling of whitespace on the first line param description Jani Nikula <jani.nikula@intel.com> - 2016-06-04 13:50 +0200
  [PATCH v2 35/38] doc/sphinx: Stop touching state_machine internals Jani Nikula <jani.nikula@intel.com> - 2016-06-04 13:50 +0200
  [PATCH v2 27/38] kernel-doc/rst: use *undescribed* instead of _undescribed_ Jani Nikula <jani.nikula@intel.com> - 2016-06-04 13:50 +0200
  [PATCH v2 09/38] sphinx: update docbook->rst conversion script match C domain spec Jani Nikula <jani.nikula@intel.com> - 2016-06-04 13:50 +0200
  Re: [PATCH v2 00/38] Documentation/sphinx Daniel Vetter <daniel@ffwll.ch> - 2016-06-04 14:20 +0200
  Re: [PATCH v2 00/38] Documentation/sphinx Jonathan Corbet <corbet@lwn.net> - 2016-06-09 22:00 +0200
    Re: [PATCH v2 00/38] Documentation/sphinx Daniel Vetter <daniel.vetter@ffwll.ch> - 2016-06-10 20:20 +0200
      Re: [PATCH v2 00/38] Documentation/sphinx Dave Airlie <airlied@gmail.com> - 2016-06-10 22:50 +0200

csiph-web