From: Daniel Vetter <daniel@ffwll.ch>
To: Jani Nikula <jani.nikula@intel.com>
Cc: Jonathan Corbet <corbet@lwn.net>,
Markus Heiser <markus.heiser@darmarit.de>,
Daniel Vetter <daniel.vetter@ffwll.ch>,
Grant Likely <grant.likely@secretlab.ca>,
Mauro Carvalho Chehab <mchehab@osg.samsung.com>,
Keith Packard <keithp@keithp.com>,
LKML <linux-kernel@vger.kernel.org>,
linux-doc@vger.kernel.org, Hans Verkuil <hverkuil@xs4all.nl>
Subject: Re: [PATCH v2 00/38] Documentation/sphinx
Date: Sat, 4 Jun 2016 14:15:00 +0200 [thread overview]
Message-ID: <20160604121500.GE14529@phenom.ffwll.local> (raw)
In-Reply-To: <cover.1465031816.git.jani.nikula@intel.com>
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
next prev parent reply other threads:[~2016-06-04 12:15 UTC|newest]
Thread overview: 47+ messages / expand[flat|nested] mbox.gz Atom feed top
2016-06-04 11:37 [PATCH v2 00/38] Documentation/sphinx Jani Nikula
2016-06-04 11:37 ` [PATCH v2 01/38] kernel-doc/rst: fix use of uninitialized value Jani Nikula
2016-06-04 11:37 ` [PATCH v2 02/38] kernel-doc: support printing exported and non-exported symbols Jani Nikula
2016-06-04 11:37 ` [PATCH v2 03/38] Documentation/sphinx: add basic working Sphinx configuration and build Jani Nikula
2016-06-04 11:37 ` [PATCH v2 04/38] Documentation: add .gitignore Jani Nikula
2016-06-04 11:37 ` [PATCH v2 05/38] Documentation/sphinx: add Sphinx kernel-doc directive extension Jani Nikula
2016-06-04 11:37 ` [PATCH v2 06/38] Documentation/sphinx: configure the kernel-doc extension Jani Nikula
2016-06-04 11:37 ` [PATCH v2 07/38] Documentation/sphinx: set version and release properly Jani Nikula
2016-06-04 11:37 ` [PATCH v2 08/38] sphinx: cheesy script to convert .tmpl files Jani Nikula
2016-06-04 11:37 ` [PATCH v2 09/38] sphinx: update docbook->rst conversion script match C domain spec Jani Nikula
2016-06-04 11:37 ` [PATCH v2 10/38] Documentation/sphinx: nicer referencing of struct in docbook->rst conversion Jani Nikula
2016-06-04 11:37 ` [PATCH v2 11/38] kernel-doc: add names for states and substates Jani Nikula
2016-06-04 11:37 ` [PATCH v2 12/38] kernel-doc: add names for output selection Jani Nikula
2016-06-04 11:37 ` [PATCH v2 13/38] kernel-doc/rst: do not output DOC: section titles for requested ones Jani Nikula
2016-06-04 11:37 ` [PATCH v2 14/38] kernel-doc/rst: reference functions according to C domain spec Jani Nikula
2016-06-04 11:37 ` [PATCH v2 15/38] kernel-doc/rst: &foo references are more universal than structs Jani Nikula
2016-06-04 11:37 ` [PATCH v2 16/38] kernel-doc/rst: add support for &union foo and &typedef foo references Jani Nikula
2016-06-04 11:37 ` [PATCH v2 17/38] kernel-doc/rst: add support for struct/union/enum member references Jani Nikula
2016-06-04 11:37 ` [PATCH v2 18/38] kernel-doc/rst: drop redundant unescape in highlighting Jani Nikula
2016-06-04 11:37 ` [PATCH v2 19/38] kernel-doc/rst: highlight function/struct/enum purpose lines too Jani Nikula
2016-06-04 11:37 ` [PATCH v2 20/38] kernel-doc: do not regard $, %, or & prefixes as special in section names Jani Nikula
2016-06-04 11:37 ` [PATCH v2 21/38] kernel-doc: fix wrong code indentation Jani Nikula
2016-06-04 11:37 ` [PATCH v2 22/38] kernel-doc/rst: blank lines in output are not needed Jani Nikula
2016-06-04 11:37 ` [PATCH v2 23/38] kernel-doc: strip leading blank lines from inline doc comments Jani Nikula
2016-06-04 11:37 ` [PATCH v2 24/38] kernel-doc/rst: change the output layout Jani Nikula
2016-06-04 11:37 ` [PATCH v2 25/38] kernel-doc: improve handling of whitespace on the first line param description Jani Nikula
2016-06-04 11:37 ` [PATCH v2 26/38] kernel-doc: strip leading whitespace from continued param descs Jani Nikula
2016-06-04 11:37 ` [PATCH v2 27/38] kernel-doc/rst: use *undescribed* instead of _undescribed_ Jani Nikula
2016-06-04 11:37 ` [PATCH v2 28/38] kernel-doc/rst: remove fixme comment Jani Nikula
2016-06-04 11:37 ` [PATCH v2 29/38] kernel-doc: limit the "section header:" detection to a select few Jani Nikula
2016-06-09 15:03 ` Jonathan Corbet
2016-06-09 16:39 ` Jani Nikula
2016-06-04 11:37 ` [PATCH v2 30/38] kernel-doc: concatenate contents of colliding sections Jani Nikula
2016-06-04 11:37 ` [PATCH v2 31/38] kernel-doc: reset contents and section harder Jani Nikula
2016-06-04 11:37 ` [PATCH v2 32/38] Documentation/sphinx: fix kernel-doc extension on python3 Jani Nikula
2016-06-04 11:37 ` [PATCH v2 33/38] doc/sphinx: Pass right filename as source Jani Nikula
2016-06-04 11:37 ` [PATCH v2 34/38] scripts/kernel-doc: Remove duplicated DOC: start handling Jani Nikula
2016-06-04 11:37 ` [PATCH v2 35/38] doc/sphinx: Stop touching state_machine internals Jani Nikula
2016-06-04 11:37 ` [PATCH v2 36/38] scripts/kernel-doc: Also give functions symbolic names Jani Nikula
2016-06-04 11:37 ` [PATCH v2 37/38] scripts/kernel-doc: Add option to inject line numbers Jani Nikula
2016-06-04 11:37 ` [PATCH v2 38/38] doc/sphinx: Track line-number of starting blocks Jani Nikula
2016-06-04 12:15 ` Daniel Vetter [this message]
2016-06-09 19:55 ` [PATCH v2 00/38] Documentation/sphinx Jonathan Corbet
2016-06-10 18:17 ` Daniel Vetter
2016-06-10 20:41 ` Dave Airlie
2016-06-14 8:15 ` Daniel Vetter
2016-06-14 19:23 ` Jonathan Corbet
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20160604121500.GE14529@phenom.ffwll.local \
--to=daniel@ffwll.ch \
--cc=corbet@lwn.net \
--cc=daniel.vetter@ffwll.ch \
--cc=grant.likely@secretlab.ca \
--cc=hverkuil@xs4all.nl \
--cc=jani.nikula@intel.com \
--cc=keithp@keithp.com \
--cc=linux-doc@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=markus.heiser@darmarit.de \
--cc=mchehab@osg.samsung.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.