This series add a small sphinx extension for extraction API doc
from the source files, similar to what 'kerneldoc' + 'kernel-doc'
do for the kernel.
It's quite simple and basic but, thanks to sphinx, already quite
powerful. As such it only supports the documentation of functions
and generic doc-blocks (the most important) but nothing yet to
document strutures, enums, typedefs or variable.
Also nothing is done to try to check if parameters in function's
documentation match the real function's parameters (the idea is
to add this later with the help of sparse itself).
Currently, only a single file have been converted to such
documention (ptrlist.c). The result can be seen on:
http://sparse-doc.readthedocs.io/en/autodoc/api.html
Now, the only thing that must be added is actual API and internal
documentation ... ahah.
The series is available for evaluation in the Git repository at:
git://github.com/lucvoo/sparse-dev.git autodoc
Changes since v1:
* only support '///' doc-blocks
* remove support for extra tags
* allow multi-line for paramaters & return
* add some meta documentation
* add some tests
* document a few more APIs
* add type annotation to the python script
Luc Van Oostenryck (13):
api: move evaluate interface to its own header file
doc: add structured doc to ptrlist.c
autodoc: extract doc from the C files
autodoc: convert extracted doc to reST
autodoc: add a sphinx c:autodoc directive for the extracted doc
autodoc: add doc from ptrlist.c
autodoc: add markup to argument's references
autodoc: doc the doc
autodoc: by default disable syntax highlighting
autodoc: add a small cheatsheet for reST markup
autodoc: support muti-line param & return descriptions
autodoc: document a few more APIs to test multiline
autodoc: add autodoc tests in the testsuite
.gitignore | 1 +
Documentation/api.rst | 21 +++
Documentation/conf.py | 12 +-
Documentation/doc-guide.rst | 151 +++++++++++++++++
Documentation/index.rst | 2 +
Documentation/sphinx/cdoc.py | 316 +++++++++++++++++++++++++++++++++++
builtin.c | 1 +
evaluate.c | 1 +
evaluate.h | 28 ++++
expand.c | 1 +
expression.h | 22 ++-
inline.c | 1 +
lib.c | 1 +
ptrlist.c | 97 +++++++++--
symbol.c | 1 +
validation/doc/cdoc.cdoc | 177 ++++++++++++++++++++
validation/test-suite | 2 +-
17 files changed, 807 insertions(+), 28 deletions(-)
create mode 100644 Documentation/api.rst
create mode 100644 Documentation/doc-guide.rst
create mode 100755 Documentation/sphinx/cdoc.py
create mode 100644 evaluate.h
create mode 100644 validation/doc/cdoc.cdoc
--
2.17.0
--
To unsubscribe from this list: send the line "unsubscribe linux-sparse" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
