Changes between Version 14 and Version 15 of TracDev/ApiDocs

Timestamp:

Sep 5, 2012, 11:09:49 AM (12 years ago)

Author:

Christian Boos

Comment:

Document #checkapidoc

TracDev/ApiDocs

@@ -55 +55 @@
 
 Same goes for `easy_install rst2pdf`.
+
+==== Verifying the completeness of the documentation -- `checkapidoc.py` #checkapidoc
+Note that we also have a help script for checking whether a documented .rst module below source:trunk/doc/api contains all the symbols that need to be documented.
+
+For example:
+{{{
+$ PYTHONPATH=. python doc/utils/checkapidoc.py trac_wiki_api
+}}}
+will check if all public and documented symbols from source:trunk/trac/wiki/api.py are referenced in source:trunk/doc/api/trac_wiki_api.rst.
+
+{{{
+$ PYTHONPATH=. python doc/utils/checkapidoc.py trac_wiki_api
+Warning: trac.wiki.api doesn't define __all__, using exported symbols.
+ * ..   autofunction :: validate_page_name
+}}}
+Explaining the output:
+
+ `Warning: trac.wiki.api doesn't define __all__, using exported symbols.` means that in the absence of an explicit list of public symbols, we try to guess what needs to be documented by looking at the globals of that module which have a docstring.
+
+ ` * ..   autofunction :: validate_page_name` corresponds to a function in [source:trunk/trac/wiki/api.py api.py] which has a docstring but is not yet present in [source:trunk/doc/api/trac_wiki_api.rst trac_wiki_api.rst].
+
+
+Note that when `__all__` is specified, we also consider that listed symbols which //don't// have yet a docstring should also be documented.
+
+A symbol can be explicitly declared to be unwanted in the Sphinx documentation by listing it in the global `__no_apidoc__` property of its defining module.
+
+There's also a verbose mode `-v` for showing all the symbols found:
+{{{
+$ PYTHONPATH=. python doc/utils/checkapidoc.py trac_wiki_api -v
+== Checking trac_wiki_api.rst ...
+Warning: trac.wiki.api doesn't define __all__, using exported symbols.
+ - OK      autoclass :: IWikiChangeListener
+ - OK      autoclass :: IWikiMacroProvider
+ - OK      autoclass :: IWikiPageManipulator
+ - OK      autoclass :: IWikiSyntaxProvider
+ - OK      autoclass :: WikiSystem
+ - OK   autofunction :: parse_args
+ * ..   autofunction :: validate_page_name
+}}}