[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]
Date: Wed, 19 Jun 2019 10:07:55 -0300
From: Mauro Carvalho Chehab <mchehab+samsung@...nel.org>
To: Peter Zijlstra <peterz@...radead.org>, Jonathan Corbet <corbet@....net>
Cc: Daniel Vetter <daniel@...ll.ch>, Linux Doc Mailing List
<linux-doc@...r.kernel.org>, Mauro Carvalho Chehab <mchehab@...radead.org>,
Linux Kernel Mailing List <linux-kernel@...r.kernel.org>, Marc Zyngier
<marc.zyngier@....com>, William Breathitt Gray <vilhelm.gray@...il.com>,
Jaroslav Kysela <perex@...ex.cz>, Greg Kroah-Hartman
<gregkh@...uxfoundation.org>, "Rafael J. Wysocki" <rafael@...nel.org>,
"Naveen N. Rao" <naveen.n.rao@...ux.ibm.com>, Anil S Keshavamurthy
<anil.s.keshavamurthy@...el.com>, "David S. Miller" <davem@...emloft.net>,
Masami Hiramatsu <mhiramat@...nel.org>, Johannes Thumshirn
<morbidrsa@...il.com>, Steffen Klassert <steffen.klassert@...unet.com>,
Sudip Mukherjee <sudipm.mukherjee@...il.com>, Andreas Färber <afaerber@...e.de>, Manivannan Sadhasivam
<manivannan.sadhasivam@...aro.org>, Rodolfo Giometti
<giometti@...eenne.com>, Richard Cochran <richardcochran@...il.com>,
Thierry Reding <thierry.reding@...il.com>, Sumit Semwal
<sumit.semwal@...aro.org>, Gustavo Padovan <gustavo@...ovan.org>, Jens
Wiklander <jens.wiklander@...aro.org>, Kirti Wankhede
<kwankhede@...dia.com>, Alex Williamson <alex.williamson@...hat.com>,
Cornelia Huck <cohuck@...hat.com>, Bartlomiej Zolnierkiewicz
<b.zolnierkie@...sung.com>, David Airlie <airlied@...ux.ie>, Maarten
Lankhorst <maarten.lankhorst@...ux.intel.com>, Maxime Ripard
<maxime.ripard@...tlin.com>, Sean Paul <sean@...rly.run>, Farhan Ali
<alifm@...ux.ibm.com>, Eric Farman <farman@...ux.ibm.com>, Halil Pasic
<pasic@...ux.ibm.com>, Heiko Carstens <heiko.carstens@...ibm.com>, Vasily
Gorbik <gor@...ux.ibm.com>, Christian Borntraeger <borntraeger@...ibm.com>,
Harry Wei <harryxiyou@...il.com>, Alex Shi <alex.shi@...ux.alibaba.com>,
Evgeniy Polyakov <zbr@...emap.net>, Jerry Hoemann <jerry.hoemann@....com>,
Wim Van Sebroeck <wim@...ux-watchdog.org>, Guenter Roeck
<linux@...ck-us.net>, Guan Xuetao <gxt@....edu.cn>, Arnd Bergmann
<arnd@...db.de>, Linus Walleij <linus.walleij@...aro.org>, Bartosz
Golaszewski <bgolaszewski@...libre.com>, Andy Shevchenko
<andy@...radead.org>, Jiri Slaby <jslaby@...e.com>,
linux-wireless@...r.kernel.org, Linux PCI <linux-pci@...r.kernel.org>,
"open list:GENERIC INCLUDE/A..." <linux-arch@...r.kernel.org>,
platform-driver-x86@...r.kernel.org, Kernel Hardening
<kernel-hardening@...ts.openwall.com>, linux-remoteproc@...r.kernel.org,
openipmi-developer@...ts.sourceforge.net, linux-crypto@...r.kernel.org,
Linux ARM <linux-arm-kernel@...ts.infradead.org>, netdev
<netdev@...r.kernel.org>, linux-pwm <linux-pwm@...r.kernel.org>, dri-devel
<dri-devel@...ts.freedesktop.org>, kvm@...r.kernel.org, Linux Fbdev
development list <linux-fbdev@...r.kernel.org>, linux-s390@...r.kernel.org,
linux-watchdog@...r.kernel.org, "moderated list:DMA BUFFER SHARING
FRAMEWORK" <linaro-mm-sig@...ts.linaro.org>, linux-gpio
<linux-gpio@...r.kernel.org>, Linux MM <linux-mm@...ck.org>
Subject: Re: [PATCH v1 12/22] docs: driver-api: add .rst files from the main
dir
Em Wed, 19 Jun 2019 12:42:39 +0200
Peter Zijlstra <peterz@...radead.org> escreveu:
> On Wed, Jun 19, 2019 at 07:22:18AM -0300, Mauro Carvalho Chehab wrote:
> > Hi Daniel,
> >
> > Em Wed, 19 Jun 2019 11:05:57 +0200
> > Daniel Vetter <daniel@...ll.ch> escreveu:
> >
> > > On Tue, Jun 18, 2019 at 10:55 PM Mauro Carvalho Chehab
> > > <mchehab+samsung@...nel.org> wrote:
> > > > diff --git a/Documentation/gpu/drm-mm.rst b/Documentation/gpu/drm-mm.rst
> > > > index fa30dfcfc3c8..b0f948d8733b 100644
> > > > --- a/Documentation/gpu/drm-mm.rst
> > > > +++ b/Documentation/gpu/drm-mm.rst
> > > > @@ -320,7 +320,7 @@ struct :c:type:`struct file_operations <file_operations>` get_unmapped_area
> > > > field with a pointer on :c:func:`drm_gem_cma_get_unmapped_area`.
> > > >
> > > > More detailed information about get_unmapped_area can be found in
> > > > -Documentation/nommu-mmap.rst
> > > > +Documentation/driver-api/nommu-mmap.rst
> > >
> > > Random drive-by comment: Could we convert these into hyperlinks within
> > > sphinx somehow, without making them less useful as raw file references
> > > (with vim I can just type 'gf' and it works, emacs probably the same).
> > > -Daniel
> >
> > Short answer: I don't know how vim/emacs would recognize Sphinx tags.
>
> No, the other way around, Sphinx can recognize local files and treat
> them special. That way we keep the text readable.
>
> Same with that :c:func:'foo' crap, that needs to die, and Sphinx needs
> to be taught about foo().
Just did a test today at Jon's extension (with is currently on a
separate branch). At least the version that it is there at his automarkup
branch still needs some work, as it currently breaks titles and tables:
6.4 :c:func:`resync_start()`, :c:func:`resync_finish()`
-----------------------------------
/devel/v4l/docs/Documentation/driver-api/md/md-cluster.rst:323: WARNING: Title underline too short.
/devel/v4l/docs/Documentation/driver-api/serial/tty.rst:74: WARNING: Malformed table.
Text in column margin in table line 34.
======================= =======================================================
:c:func:`open()` Called when the line discipline is attached to
-
That's said, once it gets fixed to address those complex cases, a
regex like:
\bDocumentation/([\w\d\-\_\/]+)\.rst\b
could be converted to :doc: tag. It should be smart enough to convert
the relative paths, as we refer to the files from the git root directory
(with makes a lot sense to me), while Sphinx :doc: use relative patches
from the location where the parsed file is.
Something like the enclosed patch.
Thanks,
Mauro
[PATCH] automarkup.py: convert Documentation/* to hyperlinks
Auto-create hyperlinks when it finds a Documentation/.. occurrence.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@...nel.org>
diff --git a/Documentation/sphinx/automarkup.py b/Documentation/sphinx/automarkup.py
index 39c8f4d5af82..9d6926b61241 100644
--- a/Documentation/sphinx/automarkup.py
+++ b/Documentation/sphinx/automarkup.py
@@ -9,6 +9,7 @@
from __future__ import print_function
import re
import sphinx
+#import sys # Just for debug
#
# Regex nastiness. Of course.
@@ -31,10 +32,26 @@ RE_literal = re.compile(r'^(\s*)(.*::\s*|\.\.\s+code-block::.*)$')
#
RE_whitesp = re.compile(r'^(\s*)')
+#
+# Get a documentation reference
+#
+RE_doc_links = re.compile(r'\bDocumentation/([\w\d\-\_\/]+)\.rst\b')
+
+#
+# Doc link false-positives
+#
+RE_false_doc_links = re.compile(r':ref:`\s*Documentation/[\w\d\-\_\/]+\.rst')
+
def MangleFile(app, docname, text):
ret = [ ]
previous = ''
literal = False
+
+ rel_dir = ''
+
+ for depth in range(0, docname.count('/')):
+ rel_dir += "../"
+
for line in text[0].split('\n'):
#
# See if we might be ending a literal block, as denoted by
@@ -63,7 +80,17 @@ def MangleFile(app, docname, text):
# Normal line - perform substitutions.
#
else:
- ret.append(RE_function.sub(r'\1:c:func:`\2`\3', line))
+ new_line = RE_function.sub(r'\1:c:func:`\2`\3', line)
+
+ if not RE_false_doc_links.search(new_line):
+ new_line = RE_doc_links.sub(r':doc:`' + rel_dir + r'\1`', new_line)
+
+ # # Just for debug - should be removed on production
+ # if new_line != line:
+ # print ("===>" + new_line, file=sys.stderr)
+
+ ret.append(new_line)
+
#
# Might we be starting a literal block? If so make note of
# the fact.
Powered by blists - more mailing lists
Confused about mailing lists and their use?
Read about mailing lists on Wikipedia
and check out these
guidelines on proper formatting of your messages.
