From mboxrd@z Thu Jan 1 00:00:00 1970 Date: Wed, 19 Jun 2019 10:07:55 -0300 From: Mauro Carvalho Chehab Subject: Re: [PATCH v1 12/22] docs: driver-api: add .rst files from the main dir Message-ID: <20190619075843.3c2464ac@coco.lan> In-Reply-To: <20190619104239.GM3419@hirez.programming.kicks-ass.net> References: <20190619072218.4437f891@coco.lan> <20190619104239.GM3419@hirez.programming.kicks-ass.net> MIME-Version: 1.0 Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: 7bit To: Peter Zijlstra , Jonathan Corbet Cc: Daniel Vetter , Linux Doc Mailing List , Mauro Carvalho Chehab , Linux Kernel Mailing List , Marc Zyngier , William Breathitt Gray , Jaroslav Kysela , Greg Kroah-Hartman , "Rafael J. Wysocki" , "Naveen N. Rao" , Anil S Keshavamurthy , "David S. Miller" , Masami Hiramatsu , Johannes Thumshirn , Steffen Klassert , Sudip Mukherjee , Andreas =?UTF-8?B?RsOkcmJl?= =?UTF-8?B?cg==?= , Manivannan Sadhasivam , Rodolfo Giometti , Richard Cochran , Thierry Reding , Sumit Semwal , Gustavo Padovan , Jens Wiklander , Kirti Wankhede , Alex Williamson , Cornelia Huck , Bartlomiej Zolnierkiewicz , David Airlie , Maarten Lankhorst , Maxime Ripard , Sean Paul , Farhan Ali , Eric Farman , Halil Pasic , Heiko Carstens , Vasily Gorbik , Christian Borntraeger , Harry Wei , Alex Shi , Evgeniy Polyakov , Jerry Hoemann , Wim Van Sebroeck , Guenter Roeck , Guan Xuetao , Arnd Bergmann , Linus Walleij , Bartosz Golaszewski , Andy Shevchenko , Jiri Slaby , linux-wireless@vger.kernel.org, Linux PCI , "open list:GENERIC INCLUDE/A..." , platform-driver-x86@vger.kernel.org, Kernel Hardening , linux-remoteproc@vger.kernel.org, openipmi-developer@lists.sourceforge.net, linux-crypto@vger.kernel.org, Linux ARM , netdev , linux-pwm , dri-devel , kvm@vger.kernel.org, Linux Fbdev development list , linux-s390@vger.kernel.org, linux-watchdog@vger.kernel.org, "moderated list:DMA BUFFER SHARING FRAMEWORK" , linux-gpio , Linux MM List-ID: Em Wed, 19 Jun 2019 12:42:39 +0200 Peter Zijlstra 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 escreveu: > > > > > On Tue, Jun 18, 2019 at 10:55 PM Mauro Carvalho Chehab > > > 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 ` 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 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. From mboxrd@z Thu Jan 1 00:00:00 1970 From: Mauro Carvalho Chehab Subject: Re: [PATCH v1 12/22] docs: driver-api: add .rst files from the main dir Date: Wed, 19 Jun 2019 10:07:55 -0300 Message-ID: <20190619075843.3c2464ac@coco.lan> References: <20190619072218.4437f891@coco.lan> <20190619104239.GM3419@hirez.programming.kicks-ass.net> Mime-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: base64 Return-path: In-Reply-To: <20190619104239.GM3419@hirez.programming.kicks-ass.net> List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dri-devel-bounces@lists.freedesktop.org Sender: "dri-devel" To: Peter Zijlstra , Jonathan Corbet Cc: Linux Fbdev development list , kvm@vger.kernel.org, Linux Doc Mailing List , David Airlie , Farhan Ali , Heiko Carstens , Jerry Hoemann , dri-devel , Jaroslav Kysela , Linux MM , Kirti Wankhede , Thierry Reding , Manivannan Sadhasivam , Kernel Hardening , Evgeniy Polyakov , netdev , Alex Shi , Steffen Klassert , linux-s390@vger.kernel.org, Arnd Bergmann , Christian Borntraeger , Guan Xuetao List-Id: linux-arch.vger.kernel.org RW0gV2VkLCAxOSBKdW4gMjAxOSAxMjo0MjozOSArMDIwMApQZXRlciBaaWpsc3RyYSA8cGV0ZXJ6 QGluZnJhZGVhZC5vcmc+IGVzY3JldmV1OgoKPiBPbiBXZWQsIEp1biAxOSwgMjAxOSBhdCAwNzoy MjoxOEFNIC0wMzAwLCBNYXVybyBDYXJ2YWxobyBDaGVoYWIgd3JvdGU6Cj4gPiBIaSBEYW5pZWws Cj4gPiAKPiA+IEVtIFdlZCwgMTkgSnVuIDIwMTkgMTE6MDU6NTcgKzAyMDAKPiA+IERhbmllbCBW ZXR0ZXIgPGRhbmllbEBmZndsbC5jaD4gZXNjcmV2ZXU6Cj4gPiAgIAo+ID4gPiBPbiBUdWUsIEp1 biAxOCwgMjAxOSBhdCAxMDo1NSBQTSBNYXVybyBDYXJ2YWxobyBDaGVoYWIKPiA+ID4gPG1jaGVo YWIrc2Ftc3VuZ0BrZXJuZWwub3JnPiB3cm90ZTogIAo+ID4gPiA+IGRpZmYgLS1naXQgYS9Eb2N1 bWVudGF0aW9uL2dwdS9kcm0tbW0ucnN0IGIvRG9jdW1lbnRhdGlvbi9ncHUvZHJtLW1tLnJzdAo+ ID4gPiA+IGluZGV4IGZhMzBkZmNmYzNjOC4uYjBmOTQ4ZDg3MzNiIDEwMDY0NAo+ID4gPiA+IC0t LSBhL0RvY3VtZW50YXRpb24vZ3B1L2RybS1tbS5yc3QKPiA+ID4gPiArKysgYi9Eb2N1bWVudGF0 aW9uL2dwdS9kcm0tbW0ucnN0Cj4gPiA+ID4gQEAgLTMyMCw3ICszMjAsNyBAQCBzdHJ1Y3QgOmM6 dHlwZTpgc3RydWN0IGZpbGVfb3BlcmF0aW9ucyA8ZmlsZV9vcGVyYXRpb25zPmAgZ2V0X3VubWFw cGVkX2FyZWEKPiA+ID4gPiAgZmllbGQgd2l0aCBhIHBvaW50ZXIgb24gOmM6ZnVuYzpgZHJtX2dl bV9jbWFfZ2V0X3VubWFwcGVkX2FyZWFgLgo+ID4gPiA+Cj4gPiA+ID4gIE1vcmUgZGV0YWlsZWQg aW5mb3JtYXRpb24gYWJvdXQgZ2V0X3VubWFwcGVkX2FyZWEgY2FuIGJlIGZvdW5kIGluCj4gPiA+ ID4gLURvY3VtZW50YXRpb24vbm9tbXUtbW1hcC5yc3QKPiA+ID4gPiArRG9jdW1lbnRhdGlvbi9k cml2ZXItYXBpL25vbW11LW1tYXAucnN0ICAgIAo+ID4gPiAKPiA+ID4gUmFuZG9tIGRyaXZlLWJ5 IGNvbW1lbnQ6IENvdWxkIHdlIGNvbnZlcnQgdGhlc2UgaW50byBoeXBlcmxpbmtzIHdpdGhpbgo+ ID4gPiBzcGhpbnggc29tZWhvdywgd2l0aG91dCBtYWtpbmcgdGhlbSBsZXNzIHVzZWZ1bCBhcyBy YXcgZmlsZSByZWZlcmVuY2VzCj4gPiA+ICh3aXRoIHZpbSBJIGNhbiBqdXN0IHR5cGUgJ2dmJyBh bmQgaXQgd29ya3MsIGVtYWNzIHByb2JhYmx5IHRoZSBzYW1lKS4KPiA+ID4gLURhbmllbCAgCj4g PiAKPiA+IFNob3J0IGFuc3dlcjogSSBkb24ndCBrbm93IGhvdyB2aW0vZW1hY3Mgd291bGQgcmVj b2duaXplIFNwaGlueCB0YWdzLiAgCj4gCj4gTm8sIHRoZSBvdGhlciB3YXkgYXJvdW5kLCBTcGhp bnggY2FuIHJlY29nbml6ZSBsb2NhbCBmaWxlcyBhbmQgdHJlYXQKPiB0aGVtIHNwZWNpYWwuIFRo YXQgd2F5IHdlIGtlZXAgdGhlIHRleHQgcmVhZGFibGUuCj4gCj4gU2FtZSB3aXRoIHRoYXQgOmM6 ZnVuYzonZm9vJyBjcmFwLCB0aGF0IG5lZWRzIHRvIGRpZSwgYW5kIFNwaGlueCBuZWVkcwo+IHRv IGJlIHRhdWdodCBhYm91dCBmb28oKS4KCkp1c3QgZGlkIGEgdGVzdCB0b2RheSBhdCBKb24ncyBl eHRlbnNpb24gKHdpdGggaXMgY3VycmVudGx5IG9uIGEKc2VwYXJhdGUgYnJhbmNoKS4gQXQgbGVh c3QgdGhlIHZlcnNpb24gdGhhdCBpdCBpcyB0aGVyZSBhdCBoaXMgYXV0b21hcmt1cApicmFuY2gg c3RpbGwgbmVlZHMgc29tZSB3b3JrLCBhcyBpdCBjdXJyZW50bHkgYnJlYWtzIHRpdGxlcyBhbmQg dGFibGVzOgoKCTYuNCA6YzpmdW5jOmByZXN5bmNfc3RhcnQoKWAsIDpjOmZ1bmM6YHJlc3luY19m aW5pc2goKWAKCS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tCgkvZGV2ZWwvdjRs L2RvY3MvRG9jdW1lbnRhdGlvbi9kcml2ZXItYXBpL21kL21kLWNsdXN0ZXIucnN0OjMyMzogV0FS TklORzogVGl0bGUgdW5kZXJsaW5lIHRvbyBzaG9ydC4KCgoJL2RldmVsL3Y0bC9kb2NzL0RvY3Vt ZW50YXRpb24vZHJpdmVyLWFwaS9zZXJpYWwvdHR5LnJzdDo3NDogV0FSTklORzogTWFsZm9ybWVk IHRhYmxlLgoJVGV4dCBpbiBjb2x1bW4gbWFyZ2luIGluIHRhYmxlIGxpbmUgMzQuCgoJPT09PT09 PT09PT09PT09PT09PT09PT0gPT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09 PT09PT09PT09PT09PT09PQoJOmM6ZnVuYzpgb3BlbigpYCAgICAgICAgICAgICAgICAgICAgICAg IENhbGxlZCB3aGVuIHRoZSBsaW5lIGRpc2NpcGxpbmUgaXMgYXR0YWNoZWQgdG8KCi0KClRoYXQn cyBzYWlkLCBvbmNlIGl0IGdldHMgZml4ZWQgdG8gYWRkcmVzcyB0aG9zZSBjb21wbGV4IGNhc2Vz LCBhCnJlZ2V4IGxpa2U6CgoJXGJEb2N1bWVudGF0aW9uLyhbXHdcZFwtXF9cL10rKVwucnN0XGIK CmNvdWxkIGJlIGNvbnZlcnRlZCB0byA6ZG9jOiB0YWcuIEl0IHNob3VsZCBiZSBzbWFydCBlbm91 Z2ggdG8gY29udmVydAp0aGUgcmVsYXRpdmUgcGF0aHMsIGFzIHdlIHJlZmVyIHRvIHRoZSBmaWxl cyBmcm9tIHRoZSBnaXQgcm9vdCBkaXJlY3RvcnkKKHdpdGggbWFrZXMgYSBsb3Qgc2Vuc2UgdG8g bWUpLCB3aGlsZSBTcGhpbnggOmRvYzogdXNlIHJlbGF0aXZlIHBhdGNoZXMKZnJvbSB0aGUgbG9j YXRpb24gd2hlcmUgdGhlIHBhcnNlZCBmaWxlIGlzLgoKU29tZXRoaW5nIGxpa2UgdGhlIGVuY2xv c2VkIHBhdGNoLgoKVGhhbmtzLApNYXVybwoKW1BBVENIXSBhdXRvbWFya3VwLnB5OiBjb252ZXJ0 IERvY3VtZW50YXRpb24vKiB0byBoeXBlcmxpbmtzCgpBdXRvLWNyZWF0ZSBoeXBlcmxpbmtzIHdo ZW4gaXQgZmluZHMgYSBEb2N1bWVudGF0aW9uLy4uIG9jY3VycmVuY2UuCgpTaWduZWQtb2ZmLWJ5 OiBNYXVybyBDYXJ2YWxobyBDaGVoYWIgPG1jaGVoYWIrc2Ftc3VuZ0BrZXJuZWwub3JnPgoKZGlm ZiAtLWdpdCBhL0RvY3VtZW50YXRpb24vc3BoaW54L2F1dG9tYXJrdXAucHkgYi9Eb2N1bWVudGF0 aW9uL3NwaGlueC9hdXRvbWFya3VwLnB5CmluZGV4IDM5YzhmNGQ1YWY4Mi4uOWQ2OTI2YjYxMjQx IDEwMDY0NAotLS0gYS9Eb2N1bWVudGF0aW9uL3NwaGlueC9hdXRvbWFya3VwLnB5CisrKyBiL0Rv Y3VtZW50YXRpb24vc3BoaW54L2F1dG9tYXJrdXAucHkKQEAgLTksNiArOSw3IEBACiBmcm9tIF9f ZnV0dXJlX18gaW1wb3J0IHByaW50X2Z1bmN0aW9uCiBpbXBvcnQgcmUKIGltcG9ydCBzcGhpbngK KyNpbXBvcnQgc3lzCQkjIEp1c3QgZm9yIGRlYnVnCiAKICMKICMgUmVnZXggbmFzdGluZXNzLiAg T2YgY291cnNlLgpAQCAtMzEsMTAgKzMyLDI2IEBAIFJFX2xpdGVyYWwgPSByZS5jb21waWxlKHIn XihccyopKC4qOjpccyp8XC5cLlxzK2NvZGUtYmxvY2s6Oi4qKSQnKQogIwogUkVfd2hpdGVzcCA9 IHJlLmNvbXBpbGUocideKFxzKiknKQogCisjCisjIEdldCBhIGRvY3VtZW50YXRpb24gcmVmZXJl bmNlCisjCitSRV9kb2NfbGlua3MgPSByZS5jb21waWxlKHInXGJEb2N1bWVudGF0aW9uLyhbXHdc ZFwtXF9cL10rKVwucnN0XGInKQorCisjCisjIERvYyBsaW5rIGZhbHNlLXBvc2l0aXZlcworIwor UkVfZmFsc2VfZG9jX2xpbmtzID0gcmUuY29tcGlsZShyJzpyZWY6YFxzKkRvY3VtZW50YXRpb24v W1x3XGRcLVxfXC9dK1wucnN0JykKKwogZGVmIE1hbmdsZUZpbGUoYXBwLCBkb2NuYW1lLCB0ZXh0 KToKICAgICByZXQgPSBbIF0KICAgICBwcmV2aW91cyA9ICcnCiAgICAgbGl0ZXJhbCA9IEZhbHNl CisKKyAgICByZWxfZGlyID0gJycKKworICAgIGZvciBkZXB0aCBpbiByYW5nZSgwLCBkb2NuYW1l LmNvdW50KCcvJykpOgorICAgICAgICByZWxfZGlyICs9ICIuLi8iCisKICAgICBmb3IgbGluZSBp biB0ZXh0WzBdLnNwbGl0KCdcbicpOgogICAgICAgICAjCiAgICAgICAgICMgU2VlIGlmIHdlIG1p Z2h0IGJlIGVuZGluZyBhIGxpdGVyYWwgYmxvY2ssIGFzIGRlbm90ZWQgYnkKQEAgLTYzLDcgKzgw LDE3IEBAIGRlZiBNYW5nbGVGaWxlKGFwcCwgZG9jbmFtZSwgdGV4dCk6CiAgICAgICAgICMgTm9y bWFsIGxpbmUgLSBwZXJmb3JtIHN1YnN0aXR1dGlvbnMuCiAgICAgICAgICMKICAgICAgICAgZWxz ZToKLSAgICAgICAgICAgIHJldC5hcHBlbmQoUkVfZnVuY3Rpb24uc3ViKHInXDE6YzpmdW5jOmBc MmBcMycsIGxpbmUpKQorICAgICAgICAgICAgbmV3X2xpbmUgPSBSRV9mdW5jdGlvbi5zdWIocidc MTpjOmZ1bmM6YFwyYFwzJywgbGluZSkKKworICAgICAgICAgICAgaWYgbm90IFJFX2ZhbHNlX2Rv Y19saW5rcy5zZWFyY2gobmV3X2xpbmUpOgorICAgICAgICAgICAgICAgIG5ld19saW5lID0gUkVf ZG9jX2xpbmtzLnN1YihyJzpkb2M6YCcgKyByZWxfZGlyICsgcidcMWAnLCBuZXdfbGluZSkKKwor ICMgICAgICAgICAgICMgSnVzdCBmb3IgZGVidWcgLSBzaG91bGQgYmUgcmVtb3ZlZCBvbiBwcm9k dWN0aW9uCisgIyAgICAgICAgICAgaWYgbmV3X2xpbmUgIT0gbGluZToKKyAjICAgICAgICAgICAg ICAgcHJpbnQgKCI9PT0+IiArIG5ld19saW5lLCBmaWxlPXN5cy5zdGRlcnIpCisKKyAgICAgICAg ICAgIHJldC5hcHBlbmQobmV3X2xpbmUpCisKICAgICAgICAgIwogICAgICAgICAjIE1pZ2h0IHdl IGJlIHN0YXJ0aW5nIGEgbGl0ZXJhbCBibG9jaz8gIElmIHNvIG1ha2Ugbm90ZSBvZgogICAgICAg ICAjIHRoZSBmYWN0LgoKCgpfX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19f X19fX19fXwpkcmktZGV2ZWwgbWFpbGluZyBsaXN0CmRyaS1kZXZlbEBsaXN0cy5mcmVlZGVza3Rv cC5vcmcKaHR0cHM6Ly9saXN0cy5mcmVlZGVza3RvcC5vcmcvbWFpbG1hbi9saXN0aW5mby9kcmkt ZGV2ZWw=