<commit_before>Document generation Guide
=========================

You need to install epydoc 3 first before go through this doc.

You could got epydoc source from epydoc svn::

    $ svn co https://svn.sourceforge.net/svnroot/epydoc

And follow epydoc's doc to install it.

Check Modules
-------------

To check what docs need to be written, use the command in source folder::

    $ epydoc --check tg

The command will gather all undocumented and no description python methods.

Generate Docs
-------------

To generate Turbogears2 API, use the command in source folder::

    $ epydoc --config docs/doc.ini

to generate API documents into tg2/apidoc folder.

You could custom the doc.ini setting to generate other type of docs.

Write Docs
----------

Note in TurboGears 2 we use reStructuredText format for doc strings.

It's a bit different from epydoc's default format.
Check docs about reStructuredText format on epydoc site.

http://epydoc.sourceforge.net/manual-docstring.html
http://epydoc.sourceforge.net/manual-othermarkup.html
http://epydoc.sourceforge.net/manual-fields.html

Debug Docs
-----------

To find where the format error is, use command::

    $ epydoc --config docs/doc.ini -v<commit_msg>Copied changes from 1.1 to docs/README.txt<commit_after>API Documentation Generation Guide
==================================

You need to install epydoc_ 3 first to generate the TurboGears API 
documentation from the source code.

You can either download a beta release from sourceforge_ or get the epydoc source from epydoc's SVN repository::

    $ svn co https://epydoc.svn.sourceforge.net/svnroot/epydoc/

Follow the documentation on the epydoc web site to install it.


Checking for missing doc strings
--------------------------------

To check which docs need to be written, use the following command in the 
top directory of the TurboGears trunk source::

    $ epydoc --check tg

The command will check that every module, class, method, and function has a description; that every parameter has a description and a type; and that every variable has a type. It will list those that don't meet these requirements.


Generating HTML docs
--------------------

Use this command in the top directory::

    $ epydoc --config docs/doc.ini

to generate the TurboGears 2 API documentation in the ``apidocs`` folder.

You can change the settings in the file ``doc.ini`` in the ``apigen`` folder 
to customize the output.


Writing docs
------------

.. note:: The TurboGears project uses reStructuredText_ format for doc strings.

It's a bit different from epydoc's default format. Check the documentation
about using reStructuredText with epydoc on the epydoc web site:

* http://epydoc.sourceforge.net/manual-docstring.html
* http://epydoc.sourceforge.net/manual-othermarkup.html
* http://epydoc.sourceforge.net/manual-fields.html


Debugging docs
--------------

If you get a formatting error and want to locate the position in the source
quickly, use the verbose mode of epydoc by supplying the ``-v`` option::

    $ epydoc --config docs/doc.ini -v


.. _epydoc: http://epydoc.sourceforge.net/
.. _sourceforge: http://sourceforge.net/project/showfiles.php?group_id=32455
.. _reStructuredText: http://docutils.sourceforge.net/rst.html
{'fraction_non_alphanumeric': 0.12146371463714638, 'fraction_numerical': 0.003997539975399754, 'mean_word_length': 3.384097035040431, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 1, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6224360', 'n_tokens_mistral': 981, 'n_tokens_neox': 905, 'n_words': 385}