Include docstrings in documentation

[GoogleCodeExporter]

To avoid duplication (and make the docs more complete), the docs should
transclude docstrings for functions and classes. Some of the information
currently only in the docs should be moved to docstrings.

Original issue reported on code.google.com by fredrik....@gmail.com on 20 Oct 2008 at 2:12

[GoogleCodeExporter]

I copied optimization and matrices documentation to docstrings in r702 and r703,
using slightly varying approaches. What do you think?

Original comment by Vinzent.Steinberg@gmail.com on 21 Oct 2008 at 9:55

[GoogleCodeExporter]

I think it needs to be built with Sphinx.

As a matter of fact, I am currently playing with autodoc. I am having trouble 
though;
when a docstring includes a heading like

    Notes
    .....

Sphinx crashes with "(SEVERE/4) Unexpected section title."

Any ideas? I looked at the new numpy documentation, and it's using markup like 
this
liberally. I have no idea why it isn't working for me.

Original comment by fredrik....@gmail.com on 21 Oct 2008 at 10:03

[GoogleCodeExporter]

Apparently this isn't possible without numpy's custom extensions.

As a workaround, I suggest using

    **Heading** 

    Text

instead of

    Heading
    -------

    Text

in docstrings.

Original comment by fredrik....@gmail.com on 22 Oct 2008 at 1:21

[GoogleCodeExporter]

See http://mpmath.googlecode.com/svn/trunk/doc/build/functions.html now.

How does it look?

A new doctest runner is needed, by the way.

Original comment by fredrik....@gmail.com on 22 Oct 2008 at 1:46

[GoogleCodeExporter]

This is quite strange. It sounds like a bug in sphinx, it should not crash due 
to
such headings.

I like the look. There are fewer examples than in the docs, however.

The doctest runner didn't work on Linux, so I can acknowledge this. :)

Original comment by Vinzent.Steinberg@gmail.com on 22 Oct 2008 at 1:50

[GoogleCodeExporter]

> I like the look. There are fewer examples than in the docs, however.

Yes, but this is only because the examples have not been written yet :)

Eventually all functions should have docstrings at least as extensive as for 
example
bernoulli(). Well, it's perhaps a bit redundant to include just as verbose
information in every one of cos, sin, tan, sec, csc, cot. So here an advantage 
over
*just* docstrings is there can be "regular" documentation in between.

> The doctest runner didn't work on Linux, so I can acknowledge this. :)

By the way, does the Sphinx build script work for you?

Original comment by fredrik....@gmail.com on 22 Oct 2008 at 2:01

[GoogleCodeExporter]

I think the "regular" documentation could be the first docstring in the file at
module level. So help(module) would give an complete overview. It would be nice 
to
have all information inside the code, accessible for interactive usage. So there
would be no redundancy.

> By the way, does the Sphinx build script work for you?

I'm getting lots of warnings like

WARNING: /home/one/src/mpmath/svn/doc/source/functions.txt:172: (WARNING/2) 
autodoc
can't import/find function 'mpmath.elliptic.jdn', it reported error: "'module' 
object
has no attribute 'jdn'",please check your spelling and sys.path

but it works.

Original comment by Vinzent.Steinberg@gmail.com on 22 Oct 2008 at 8:37

[GoogleCodeExporter]

> I think the "regular" documentation could be the first docstring in the file 
at
> module level. So help(module) would give an complete overview. It would be 
nice to
> have all information inside the code, accessible for interactive usage. So 
there
> would be no redundancy.

I agree. The readability can however sometimes be improved by having glue text
between the docstrings, and not just everything at the top.

> I'm getting lots of warnings like

Don't those warnings also show up in the output too?

This should be debugged; the build script ought to just work. If you can't 
figure out
why it's broken for you, consider asking the friendly people on the sphinx-dev 
list.

Original comment by fredrik....@gmail.com on 23 Oct 2008 at 1:46

[GoogleCodeExporter]

Do you think all documentation should be moved when possible to the code? (See
linalg.py for example.)

Pro:
* help(mpmath.module) works
* everything "in one place", less duplication

Contra:
* cluttered or too big source files

Original comment by Vinzent.Steinberg@gmail.com on 25 Jan 2009 at 11:36

[GoogleCodeExporter]

A problem is that the best documentation layout doesn't necessarily correspond 
to the
module layout. But yes, this can probably done to a greater extent.

Original comment by fredrik....@gmail.com on 25 Jan 2009 at 11:59

[GoogleCodeExporter]

I think this is no problem, because we can define the layout in doc/source. 
Only the
content is stored in docstrings.

Original comment by Vinzent.Steinberg@gmail.com on 25 Jan 2009 at 12:05