lwn.git/scripts, branch docs-5.13

docs: sphinx-pre-install: don't barf on beta Sphinx releases

2021-04-15T22:01:50+00:00

sphinx-pre-install is picky when it comes to parsing sphinx versions; it failed when run with sphinx 4.0.0b1. Tweak the regex to tolerate a trailing "bN" on the version number. Signed-off-by: Jonathan Corbet

scripts: kernel-doc: improve parsing for kernel-doc comments syntax

2021-04-15T21:26:06+00:00

Currently kernel-doc does not identify some cases of probable kernel doc comments, for e.g. pointer used as declaration type for identifier, space separated identifier, etc. Some example of these cases in files can be: i)" * journal_t * jbd2_journal_init_dev() - creates and initialises a journal structure" in fs/jbd2/journal.c ii) "* dget, dget_dlock - get a reference to a dentry" in include/linux/dcache.h iii) " * DEFINE_SEQLOCK(sl) - Define a statically allocated seqlock_t" in include/linux/seqlock.h Also improve identification for non-kerneldoc comments. For e.g., i) " * The following functions allow us to read data using a swap map" in kernel/power/swap.c does follow the kernel-doc like syntax, but the content inside does not adheres to the expected format. Improve parsing by adding support for these probable attempts to write kernel-doc comment. Suggested-by: Jonathan Corbet Link: https://lore.kernel.org/lkml/87mtujktl2.fsf@meer.lwn.net Signed-off-by: Aditya Srivastava Link: https://lore.kernel.org/r/20210414192529.9080-1-yashsri421@gmail.com [ jc: fixed some line-length issues ] Signed-off-by: Jonathan Corbet

scripts: get_abi: ignore code blocks for cross-references

2021-03-31T19:53:16+00:00

The script should not generate cross-references inside literal blocks. Signed-off-by: Mauro Carvalho Chehab Link: https://lore.kernel.org/r/a590f994f8a5742db333bde69e88241a080e4fe0.1616668017.git.mchehab+huawei@kernel.org Signed-off-by: Jonathan Corbet

scripts: get_abi.pl: parse description line per line

2021-03-31T19:53:16+00:00

Change the description parsing logic in rst mode in order to parse it line per line. The end result is the same, but doing line per line allows to add some code to escape literal blocks when seeking for cross-references. Signed-off-by: Mauro Carvalho Chehab Link: https://lore.kernel.org/r/d33cfa2e59ecf8f28d4ed7de7402468cf2168921.1616668017.git.mchehab+huawei@kernel.org Signed-off-by: Jonathan Corbet

scripts: get_abi.pl: extend xref match to other types

2021-03-31T19:53:16+00:00

Currently, there are "What:" symbols for more than just /sys. Extend the regex to also cover configfs, /proc /dev and /kvd symbols. Signed-off-by: Mauro Carvalho Chehab Link: https://lore.kernel.org/r/a1c7e2b2c37ed6e111dfc8641deb37ed96375a63.1616668017.git.mchehab+huawei@kernel.org Signed-off-by: Jonathan Corbet

get_abi.pl: fix xref boundaries

2021-03-31T19:53:16+00:00

There are some issues with the regex that seeks for What: cross references: basically, it is mis-identifying the start and the end boundaries of the regex, which causes :ref: to be inseerted for the wrong symbols at the wrong places. Fix it. Signed-off-by: Mauro Carvalho Chehab Link: https://lore.kernel.org/r/79a14d2518499b76931b5f29c50979987108152d.1616668017.git.mchehab+huawei@kernel.org Signed-off-by: Jonathan Corbet

get_abi.pl: seek for all occurrences for Documentation/ABI

2021-03-31T19:53:15+00:00

Instead of retrieving just one match at most, ensure that the entire description will be parsed. Signed-off-by: Mauro Carvalho Chehab Link: https://lore.kernel.org/r/17019b73e106d1b1b353b8880ed189bad3604c13.1616668017.git.mchehab+huawei@kernel.org Signed-off-by: Jonathan Corbet

scripts: get_abi.pl: better handle escape chars on what:

2021-03-31T19:53:15+00:00

The parser for the symbols defined on What: doesn't cover all chars that need to be scaped, like '{' and '}'. Change the logic to be more generic, and ensure that the same regex will be used on both What: and when parsing the cross-references. Signed-off-by: Mauro Carvalho Chehab Link: https://lore.kernel.org/r/29cb56def89b508fe605bcd2ba74a4376cc08e35.1616668017.git.mchehab+huawei@kernel.org Signed-off-by: Jonathan Corbet

scripts: kernel-doc: add warning for comment not following kernel-doc syntax

2021-03-29T23:08:28+00:00

Currently, kernel-doc start parsing the comment as a kernel-doc comment if it starts with '/**', but does not take into account if the content inside the comment too, adheres with the expected format. This results in unexpected and unclear warnings for the user. E.g., running scripts/kernel-doc -none mm/memcontrol.c emits: "mm/memcontrol.c:961: warning: expecting prototype for do not fallback to current(). Prototype was for get_mem_cgroup_from_current() instead" Here kernel-doc parses the corresponding comment as a kernel-doc comment and expects prototype for it in the next lines, and as a result causing this warning. Provide a clearer warning message to the users regarding the same, if the content inside the comment does not follow the kernel-doc expected format. Signed-off-by: Aditya Srivastava Link: https://lore.kernel.org/r/20210329092945.13152-1-yashsri421@gmail.com Signed-off-by: Jonathan Corbet

docs: kernel-doc: properly recognize parameter lines with colons

2021-03-26T19:16:35+00:00

The previous attempt to properly handle literal blocks broke parsing of parameter lines containing colons; fix it by tweaking the regex to specifically exclude the "::" pattern while accepting lines containing colons in general. Add a little documentation to the regex while in the neighborhood. Reported-by: Stephen Rothwell Fixes: 8d295fbad687 ("kernel-doc: better handle '::' sequences") Signed-off-by: Jonathan Corbet