Message-ID: <20200911133339.327721-1-nfraprado@protonmail.com>
Date:   Fri, 11 Sep 2020 13:34:27 +0000
From:   Nícolas F. R. A. Prado 
        <nfraprado@...tonmail.com>
To:     Jonathan Corbet <corbet@....net>
Cc:     linux-doc@...r.kernel.org, linux-kernel@...r.kernel.org,
        lkcamp@...ts.libreplanetbr.org, andrealmeid@...labora.com
Subject: [PATCH 0/3] docs: Add automatic cross-reference for documentation pages

Cross-referencing from a documentation page to another can be done using the
:doc:`doc-file` directive from Sphinx.
This however introduces markup that could be avoided to increase readability 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 matches'
text for the appropriate markup and is necessary for the automatic markup of
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 markup.
Since this automarkup doesn't work with relative paths (they always need to
start at Documentation/), it will almost always require more typing than the
equivalent :doc:`sphinx`, but it's purpose is to avoid the markup, making it
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-referencing
kernel-doc functions and types (using the new automarkup, so it also serves as a
testcase for it).

Thanks,
Nícolas

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

Nícolas 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(-)

-- 
2.28.0

Powered by blists - more mailing lists