Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 23.128.96.18 as permitted sender) client-ip=23.128.96.18;
Date:   Fri, 11 Sep 2020 13:34:27 +0000
To:     Jonathan Corbet <corbet@lwn.net>
From:   =?utf-8?Q?N=C3=ADcolas_F=2E_R=2E_A=2E_Prado?= 
        <nfraprado@protonmail.com>
Cc:     linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org,
        lkcamp@lists.libreplanetbr.org, andrealmeid@collabora.com
Reply-To: =?utf-8?Q?N=C3=ADcolas_F=2E_R=2E_A=2E_Prado?= 
          <nfraprado@protonmail.com>
Subject: [PATCH 0/3] docs: Add automatic cross-reference for documentation pages
Message-ID: <20200911133339.327721-1-nfraprado@protonmail.com>
MIME-Version: 1.0
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: quoted-printable
Sender: linux-kernel-owner@vger.kernel.org
Precedence: bulk

Cross-referencing from a documentation page to another can be done using th=
e
:doc:`doc-file` directive from Sphinx.
This however introduces markup that could be avoided to increase readabilit=
y in
plain text.
This patch series adds automatic markup for cross-referencing between
documentation pages.

This patch series depends on [1].

The first patch refactors the automarkup script to split regex matching and
iteration into one function and text markup substitution into another.
This enables each regex to have its own function that substitutes its match=
es'
text for the appropriate markup and is necessary for the automatic markup o=
f
documentation pages since it requires slightly different logic from marking=
 up
C references.

The second patch adds automatic markup for cross-referencing documentation
pages by adding an appropriate regex and function to do the markup.
This enables a text like "See Documentation/doc-guide/sphinx.rst." to be
substituted by a cross-reference to that document without any additional ma=
rkup.
Since this automarkup doesn't work with relative paths (they always need to
start at Documentation/), it will almost always require more typing than th=
e
equivalent :doc:`sphinx`, but it's purpose is to avoid the markup, making i=
t
more readable in plain text.
The .rst extension was left as optional in the regex matching, even though =
it
only makes sense for .rst documents, because I thought not specifying the
extension, like "See Documentation/doc-guide/sphinx." also made sense as a
cross-reference.

The third patch adds a section about cross-referencing in the "Writing
Documentation" chapter since there was none (other than the one regarding
kernel-doc).
The section describes how to use the new automatic cross-referencing for
documentation pages, and also how to use the already in place Sphinx doc
directive.
It also points to the kernel-doc document for information on cross-referenc=
ing
kernel-doc functions and types (using the new automarkup, so it also serves=
 as a
testcase for it).

Thanks,
N=C3=ADcolas

[1]: https://lore.kernel.org/linux-doc/20200903005747.3900333-1-nfraprado@p=
rotonmail.com/

N=C3=ADcolas F. R. A. Prado (3):
  docs: Allow multiple automarkup functions
  docs: Add automatic cross-reference for documentation pages
  docs: Document cross-referencing between documentation pages

 Documentation/doc-guide/sphinx.rst |  17 ++++
 Documentation/sphinx/automarkup.py | 134 ++++++++++++++++++++---------
 2 files changed, 109 insertions(+), 42 deletions(-)

--=20
2.28.0