[TIP] - ATP problem

[Paul Hildebrandt]

Yoav,

You may be interested in 
http://svn.sat.qc.ca/trac/miville/browser/trunk/py/docs/generate_modules.py
It's a little program that they put together to build the rst stubs for 
you.  I seem to remember reading somewhere that this feature may be 
included in Sphinx 0.7. 

Just as Jesse said, Sphinx was designed for writing docs not generating 
them from code.  Generation is more of epydoc's domain.  I like the look 
of Sphinx better so I've been looking for something to make Sphinx 
generate docs and the script that I linked was the closest I found.

Paul

Jesse Noller wrote:
> It's intentionally half-automatic. I generally create stubs like this:
>
> from test_flub.rst
>
> .. _shortname:
>
> ============================
> :mod:`foobar.test_flub` --- Flub tests
> ============================
>
> .. automodule:: foobar.test_flub
>     :members:
>
> This will extract all of the doc strings from the module - but I can
> then override/add-to the doc strings inline in the rst (see "Options
> and advanced usage" at http://sphinx.pocoo.org/ext/autodoc.html
>
> If you're looking for a true API-autodoc tool; you need to look at
> something else. Sphinx is great for automatically doing *some* of it
> (as above) but it's mainly made for *writing docs* - not just
> generating them from code.
>
> On Thu, Aug 27, 2009 at 12:23 AM, yoav glazner<yoavglazner at gmail.com> wrote:
>   
>> I have tried to play with the auto-doc ext and it seems to be half
>> automatic, isn't there a way to automatically take unit test and make a
>> docuent/html that explains the tests?
>>
>> On Wed, Aug 19, 2009 at 4:05 PM, Jesse Noller <jnoller at gmail.com> wrote:
>>     
>>> For test specifications; I've tended to use Sphinx (sphinx.pocoo.org)
>>> and the autodoc extension. I tend to document my tests and modules
>>> pretty heavily, and so doing this allows me to extract nice-looking
>>> and easy to use documentation from my tests, and accentuate as needed.
>>>
>>> The nice thing with doing it this way, is that you can add further
>>> examples/notes/etc on top of what is within the test code itself. It
>>> also helps keep you disciplined about documentation on the tests and
>>> any supporting modules. All of the docs are in Restructured Text,
>>> which is close to the perfect markup :)
>>>
>>> On Wed, Aug 19, 2009 at 7:07 AM, yoav glazner<yoavglazner at gmail.com>
>>> wrote:
>>>       
>>>> Hi all,
>>>> I have a problem in my work, they want me to an "ATP".
>>>> which means a long Word document that expalains what tests are made.
>>>> no one will ever really read this document.
>>>> i was thinking on making the acceptance tests on top of
>>>> unittest/pymock/nose
>>>> and generate someting like the ATP,
>>>> from the testFunctions docs.
>>>> is something like this already available?
>>>> Thanks a lot,
>>>> Yoav Glazner
>>>>