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
