[RFC PATCH 0/2] docs: automarkup.py: Add literal markup of known constants

From: Nícolas F. R. A. Prado
Date: Tue Jun 08 2021 - 21:44:18 EST


Hi,

a while back Matthew suggested adding automatic markup of known constants, like
NULL and error codes, as literals [1]. This is a great idea since those literals
are very frequently used throughout the documentation and are fixed names, so we
can easily match them without false positives and make the source files less
cluttered.

Patch 1 adds that feature to automarkup.py, while patch 2 removes the no longer
needed markup from the xarray.rst file which was given as an example.

Some things I'd like to discuss:

* As a first draft I added the constants I found on xarray.rst plus all error
codes from errno-base.h and errno.h. We don't need to start with everything,
but we can certainly do better than this. What are common constants that
should be added here? (Matthew mentioned ANSI C or POSIX, some reference to
the constants in those would be great, even more if they are easily parsable)

* The Literals list added is already a bit big with just the error codes, so
perhaps we should move them to a separate plain text file that is read on
startup?

* There was also mention of automatically converting uppercase words to
literals. I'm not so sure about that one so I left it out for now.

The example given was XA_MARK_0, which is a #define in xarray.h. The way
to go here is certainly to first use kernel-doc to get it included in the
documentation, and then cross-reference to it. FWICT at the moment kernel-doc
for defines should be done like for functions (but the parenthesis can be
omitted, although they show up in the output):

/**
* XA_MARK_0 - Brief description.
*
* Description of the type.
*/

At the current state, the cross-reference would then need to be done either
through plain :c:macro:`XA_MARK_0`, or, by relying on automarkup, typedef
XA_MARK_0 (which is not ideal since this isn't a typedef). Options for
improvements would be to add 'macro' as a possible prefix (so eg. macro
XA_MARK_0), or go all out and try to cross-reference on every uppercase word
like suggested. We should strive for what is the most natural to write, as
long as the regex isn't too broad.

Since automarkup.py is opt-out rather than opt-in, I think we should be extra
careful not to make the regexes too broad, even if in this case it relies on a
C symbol being present.

One other idea I had was that we could limit to all uppercase words as
long as it has an _ on it, since I don't expect we would get false positives
with that. The downside is that it might be very confusing to people why their
MACRONAME isn't being automatically cross-referenced to...

Thanks,
Nícolas

[1] https://lore.kernel.org/linux-doc/20201007234024.GY20115@xxxxxxxxxxxxxxxxxxxx/

Nícolas F. R. A. Prado (2):
docs: automarkup.py: Add literal markup of known constants
XArray: Remove literal markup from known constants

Documentation/core-api/xarray.rst | 48 +++++++++++++++---------------
Documentation/sphinx/automarkup.py | 45 ++++++++++++++++++++++++++--
2 files changed, 67 insertions(+), 26 deletions(-)

--
2.32.0