[Epydoc-devel] Planning for 3.0

[Daniele V. <dan...@gm...>]

ulimit -c unlimited...

Hello Edward,

what about setting a laundry list of things we want to be fixed to roll
out a beta version of Epydoc 3.0?

I think the greatest part of the work is done: Epydoc is already
something that does things no other Python API generator does - by far
(mostly thanks to all your efforts into the parsing/introspecting system).

Here is a laundry list of things i'd like to discuss AND to code if this
would concretely bring us near to the release. Feel free to 
add/delete/update items (all the __methods__ have been implemented :)

  - exclusion list (SF #1209634) would help big project to adopt Epydoc
    (just committed in the trunk a first version)

  - pretty printing (see also SF #1628044). How to represent an object
    value?
    - repr() is fine only for int and for classes that specifically
      return a parsable representation, such as datetime. Even floats
      (such as 0.1) often have an ugly representation.
    - fall back on the parsed version if available and the repr() result
      matches an  ugly pattern looks like "<something>"?
    - fall back on str()ingification?
    - prettyprinting of lists, dicts etc? More clever truncation of long
      representations?
    - if a variable value fits on a single row, omit the detail box?
    - ???

  - parsing some "#:" comments into functions body as they were part of
    the function docstring. It would keep some additional information
    close to the code implementing it, making the task to keep the API
    consistent with the code easier. Es.

     def getDigitsNumber(num):
         """Return the number of digits of a number."""

         ...there may be other code

         #: :warning: the current implementation only allows
         #:           positive numbers
         return floor(log(num) / log(10)) + 1

    Some tags (note, bug, warning, todo) are really best placed next the
    code to be documented; precondition and postcondition would be nice
    close to an assert etc.

  - using some module __variable__ as a tag (only the ones widely used:
    __version__ above all, but we may be friendly with __author__ etc;
    people has already been warned not to abuse of such variables, though
    i couldn't find a reference)

  - docutils :python: directive to allow examples to appear as colored
    Python code

  - :api: role to allow docutils documents to refer to Epydoc generated
    API. See for example
http://www.initd.org/tracker/psycopg/browser/psycopg2/trunk/scripts/ext2html.py

  - more compact html code, for which the exp-compact-html branch is
    open. In some personal audits i had, somebody complained about the
    signal/noise ratio in HTML output.

Together with setting a goal in terms of features, i'd love to QA Epydoc
against the most prominent OS projects, such TurboGears (i just read
they are having documentation issues - cfr.
http://groups.google.it/group/turbogears/browse_thread/thread/ae0e52ff3f9fde60?hl=en 
for example).

I was very sad when i read (just a couple of weeks ago, but the issues
were older) how Twisted guys were disappointed by Epydoc no more
fulfilling their needs, up to decide to write their own API
generator (http://codespeak.net/~mwh/pydoctor/).

I'd like to check Epydoc against a list of packages, including some not 
specifically thought to be inspected by Epydoc. The goal is:
  - Epydoc must not crash (modulo the most magic corners, which now can
    be removed from the list of modules to be introspected)
  - The generation result shall be presented to the packages developers,
    both to gather feedback about Epydoc output and to advertise Epydoc
    to the community. Eventually making people happy to write
    documentation...

A list of beasts to test against may include:

  - WxPython
  - Django
  - Turbogears
  - Twisted
  - SqlAlchemy
  - docutils

Daniele

...core dumped