Edgewall Software

Changes between Version 14 and Version 15 of TracDev/ApiDocs


Ignore:
Timestamp:
Sep 5, 2012, 11:09:49 AM (10 years ago)
Author:
Christian Boos
Comment:

Document #checkapidoc

Legend:

Unmodified
Added
Removed
Modified
  • TracDev/ApiDocs

    v14 v15  
    5555
    5656Same goes for `easy_install rst2pdf`.
     57
     58==== Verifying the completeness of the documentation -- `checkapidoc.py` #checkapidoc
     59Note 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.
     60
     61For example:
     62{{{
     63$ PYTHONPATH=. python doc/utils/checkapidoc.py trac_wiki_api
     64}}}
     65will 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.
     66
     67{{{
     68$ PYTHONPATH=. python doc/utils/checkapidoc.py trac_wiki_api
     69Warning: trac.wiki.api doesn't define __all__, using exported symbols.
     70 * ..   autofunction :: validate_page_name
     71}}}
     72Explaining the output:
     73
     74 `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.
     75
     76 ` * ..   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].
     77
     78
     79Note that when `__all__` is specified, we also consider that listed symbols which //don't// have yet a docstring should also be documented.
     80
     81A 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.
     82
     83There's also a verbose mode `-v` for showing all the symbols found:
     84{{{
     85$ PYTHONPATH=. python doc/utils/checkapidoc.py trac_wiki_api -v
     86== Checking trac_wiki_api.rst ...
     87Warning: trac.wiki.api doesn't define __all__, using exported symbols.
     88 - OK      autoclass :: IWikiChangeListener
     89 - OK      autoclass :: IWikiMacroProvider
     90 - OK      autoclass :: IWikiPageManipulator
     91 - OK      autoclass :: IWikiSyntaxProvider
     92 - OK      autoclass :: WikiSystem
     93 - OK   autofunction :: parse_args
     94 * ..   autofunction :: validate_page_name
     95}}}