Autodocs for simplify

[Aaron S. Meurer]

I tried creating an autodoc file for the functions in simplify.py, but
I couldn't get it to work. I followed the example of other files like
doc/src/modules/solvers.txt and created a file called simplify.txt
with this text:

Simplify
========

.. currentmodule:: sympy.simplify

Simplify
--------
.. automethod:: sympy.simplify.simplify

But Sphinx gives
[...]
doc/src/modules/simplify.txt:8: (WARNING/2) autodoc can't import/find
method 'sympy.simplify.simplify', it reported error: "'function'
object has no attribute 'simplify'", please check your spelling and
sys.path
[...]

I don't know very much about Sphinx and autodoc, so I may be doing
something wrong, but based on the output from Sphinx, I believe the
problem may have to do with the fact that "simplify" the module and
"simplify" the function both have the same name. For example,

>>> import sympy
>>> type(sympy.solvers)
<type 'module'>
>>> type(sympy.simplify)
<type 'function'>

Is there a way around this, or do we need to change the name of
"simplify" the module to something else, like "simplifiers"?

Aaron Meurer

[Ondrej Certik]

Please post your branch somewhere, I'll look into it.

Ondrej

[Aaron S. Meurer]

http://github.com/asmeurer/sympy/tree/doc-day

It also has my stuff from doc day (I wanted to include an example from
simplify).

Aaron

[Ondrej Certik]

On Sun, Jul 5, 2009 at 7:30 PM, Aaron S. Meurer<asme...@gmail.com> wrote:
>
> http://github.com/asmeurer/sympy/tree/doc-day
>
> It also has my stuff from doc day (I wanted to include an example from
> simplify).

Apply the following patch that fixes it:

$ git diff
diff --git a/doc/src/modules/simplify.txt b/doc/src/modules/simplify.txt
index 1311e55..560a7d0 100644
--- a/doc/src/modules/simplify.txt
+++ b/doc/src/modules/simplify.txt
@@ -1,8 +1,8 @@
Simplify
========

-.. currentmodule:: sympy.simplify
+.. currentmodule:: sympy.simplify.simplify

Simplify
--------
-.. automethod:: sympy.simplify.simplify
\ No newline at end of file
+.. autofunction:: simplify

Btw, I noticed that there are lots of warnings during the building of
docs, so those should all be fixed too.

Ondrej

[Aaron S. Meurer]

OK, that patch worked for simplify(). However, I had some problems
getting some of the other functions to work. You can pull again from
the same branch to see what I mean. I had to change "autofunction" to
"function" for a handful of functions because sphinx wouldn't compile
otherwise.

Aaron

[Ondrej Certik]

On Sun, Jul 5, 2009 at 9:14 PM, Aaron S. Meurer<asme...@gmail.com> wrote:
>
> OK, that patch worked for simplify().  However, I had some problems
> getting some of the other functions to work.  You can pull again from
> the same branch to see what I mean.  I had to change "autofunction" to
> "function" for a handful of functions because sphinx wouldn't compile
> otherwise.

After applying:

$ git diff
diff --git a/doc/src/modules/simplify.txt b/doc/src/modules/simplify.txt

index f41c3ab..cf76929 100644
--- a/doc/src/modules/simplify.txt
+++ b/doc/src/modules/simplify.txt
@@ -9,7 +9,7 @@ simplify

collect
-------
-.. function:: collect
+.. autofunction:: collect

separate
--------

you will get during compilation:

$ make html
rm -rf sphinx
mkdir -p _build/html/
rst2html src/sympy-patches-tutorial.txt > _build/html/spt-printable.html
mkdir -p src/.static
mkdir -p _build/html _build/doctrees
mkdir -p src/modules
PYTHONPATH=.. sphinx-build -b html -d _build/doctrees -D
latex_paper_size= src _build/html
Sphinx v0.5.2, building html
loading pickled environment... done
building [html]: targets for 1 source files that are out of date
updating environment: 0 added, 1 changed, 0 removed
reading sources... modules/simplify reST markup error:
/home/ondrej/repos/sympy/sympy/simplify/simplify.py:docstring of
collect:113: (SEVERE/4) Unexpected section title.

Notes
=====
make: *** [html] Error 1

which loosely speaking means: "your docstring for the function collect
is wrong, here is what is wrong:

Notes
=====
"

so you look into sympy/simplify/simplify.py, find the collect
function, you can see:

"""
>>> collect(a*D(D(f,x),x)**2 + b*D(D(f,x),x)**2, D(f,x)) == \
(a + b)*D(D(f,x),x)**2
True

Notes
=====
- arguments are expected to be in expanded form, so you might
have to call
.expand() prior to calling this function.
"""

so it's clear what is wrong --- the Notes is a section title, but it
is inconsistent with the rest of our docs. So for example this patch
fixes it:

diff --git a/sympy/simplify/simplify.py b/sympy/simplify/simplify.py
index c24613f..65d015c 100644
--- a/sympy/simplify/simplify.py
+++ b/sympy/simplify/simplify.py
@@ -453,8 +453,7 @@ def collect(expr, syms, evaluate=True, exact=False):
True

- Notes
- =====
+ *Notes*
- arguments are expected to be in expanded form, so you might have to c
.expand() prior to calling this function.
"""

Ondrej