From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.2 (2018-09-13) on archive.lwn.net X-Spam-Level: X-Spam-Status: No, score=-5.8 required=5.0 tests=DKIM_INVALID,DKIM_SIGNED, MAILING_LIST_MULTI,RCVD_IN_DNSWL_HI,SPF_HELO_NONE,SPF_NONE autolearn=ham autolearn_force=no version=3.4.2 Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by archive.lwn.net (Postfix) with ESMTP id 971347D2F0 for ; Wed, 19 Jun 2019 15:02:34 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1726009AbfFSPCe (ORCPT ); Wed, 19 Jun 2019 11:02:34 -0400 Received: from bombadil.infradead.org ([198.137.202.133]:50968 "EHLO bombadil.infradead.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1725899AbfFSPCe (ORCPT ); Wed, 19 Jun 2019 11:02:34 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=infradead.org; s=bombadil.20170209; h=Content-Transfer-Encoding: Content-Type:MIME-Version:References:In-Reply-To:Message-ID:Subject:Cc:To: From:Date:Sender:Reply-To:Content-ID:Content-Description:Resent-Date: Resent-From:Resent-Sender:Resent-To:Resent-Cc:Resent-Message-ID:List-Id: List-Help:List-Unsubscribe:List-Subscribe:List-Post:List-Owner:List-Archive; bh=FDFL6FNwMO+N2Z7jWsOhRNSUjHzRNRrq16HYq8Dyh38=; b=H02KpYZ7ruYvHwfH7uxOGeNVR 31p9TXM4uwYkgvcddya5pywozyXwJCwoPGcsHKtaDMTTJPFiDpIqnYZ+rKRpTcWF0XmZe0MZbbLzi RAeeF5C+uyoN5Vzbcb7URPbiCV7cH/x0c9gERr8CMbnTbXUwV09cdQViE3GrP83nq/3zr11kMHsL9 hU6MBkOm2YeWN/7qgK5nJxuyzgZq9xzNE3PI5EQ4ykwIDhMplp+TyQweP/oE6JXy7RzUT9psv6pf4 t0/oY/z4zS3mMoQrQHmhKOsIfNdyrsy2AgSgK5lGK7zRde24ZDtMo7UY+bXrq0CwDiEWsjTuM3YBA pc5i6WViQ==; Received: from 177.133.86.196.dynamic.adsl.gvt.net.br ([177.133.86.196] helo=coco.lan) by bombadil.infradead.org with esmtpsa (Exim 4.92 #3 (Red Hat Linux)) id 1hdc6b-0008Kr-9b; Wed, 19 Jun 2019 15:02:33 +0000 Date: Wed, 19 Jun 2019 12:02:29 -0300 From: Mauro Carvalho Chehab To: Jonathan Corbet Cc: Peter Zijlstra , Linux Doc Mailing List , Linux Kernel Mailing List Subject: Re: [PATCH v1 12/22] docs: driver-api: add .rst files from the main dir Message-ID: <20190619120229.78ce6e07@coco.lan> In-Reply-To: <20190619081353.75762028@lwn.net> References: <20190619072218.4437f891@coco.lan> <20190619104239.GM3419@hirez.programming.kicks-ass.net> <20190619081353.75762028@lwn.net> X-Mailer: Claws Mail 3.17.3 (GTK+ 2.24.32; x86_64-redhat-linux-gnu) MIME-Version: 1.0 Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: 7bit Sender: linux-doc-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-doc@vger.kernel.org Hi Jon, Em Wed, 19 Jun 2019 08:13:53 -0600 Jonathan Corbet escreveu: > On Wed, 19 Jun 2019 12:42:39 +0200 > Peter Zijlstra wrote: > > > 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(). > > I did a patch to make that latter part happen, but haven't been able to > find the time to address the comments and get it out there. It definitely > cleaned up the source files a lot and is worth doing. Will try to get > back to it soon. See my comment. Yeah, the :c:func:'foo' (the version you merged at the automarkup branch) has currently a bug, when there's something like: func() ====== or when func() is inside a table. Solving the table case would be a lot better if the plugin could run the existing table parser and only then handle the cross-reference replacements, but I've no idea how flexible the Sphinx plugins can be. > > The local file links should be easy to do; we shouldn't need to add any > markup for those. Yeah, those are easy - except if someone adds a Documentation/* link inside a table or inside a topic header. Running a modified version of your tool shows just two new warnings: Documentation/translations/ja_JP/howto.rst:176: WARNING: undefined label: :doc: (if the link has no caption the label must precede a section header) Documentation/translations/zh_CN/process/submitting-drivers.rst:25: WARNING: unknown document: ../../../Documentation/translations/zh_CN/process/submitting-patches The first one is because of this: :Ref:`Documentation/process/kernel-docs.rst ` (my parser didn't consider upper-case tags - a simple fix at a regex should fix this) The second one is because the URL is wrong. It is pointing to: Documentation/Documentation/translations/zh_CN/process/submitting-patches at Chinese translation. So, at least the way our documentation is, the plugin seems to be working as expected. As a reference, I'm enclosing the diff against your patch: commit 6231d7456e87bd3e11f892709945887bd55a8a20 (docs/automarkup) Author: Jonathan Corbet Date: Thu Apr 25 07:55:07 2019 -0600 Docs: An initial automarkup extension for sphinx Rather than fill our text files with :c:func:`function()` syntax, just do the markup via a hook into the sphinx build process. As is always the case, the real problem is detecting the situations where this markup should *not* be done. Signed-off-by: Jonathan Corbet Thanks, Mauro - diff --git a/Documentation/sphinx/automarkup.py b/Documentation/sphinx/automarkup.py index 39c8f4d5af82..60dad596c790 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,18 @@ 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) + new_line = 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.