[TIP] - ATP problem

[Jesse Noller]

Beyond the look and feel, being able to mix prose/examples and
doctests within the RST files where you are doing autodoc style stuff
is really nice.

On Thu, Aug 27, 2009 at 11:43 AM, Paul
Hildebrandt<Paul.Hildebrandt at disneyanimation.com> wrote:
> 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
>>>>>
>
>