Bring plot/plot3d/parametric_surface.pyx to 100% doctest coverage

[kcrisman]

Bring plot/plot3d/parametric_surface.pyx to 100% doctest coverage.

[kcrisman]

Based on Sage 4.4

[kcrisman]

Also fixes a few inconsistencies with formula for MobiusStrip? that wasn't used and dual() that I checked with robertwb.

[mvngu]

The patch  trac_8804-param-surface-docs.patch is OK by me. I have added a reviewer patch that fixes some typos, add the parametric surface module to the reference manual, and fixes to get the module to build and resolve all warnings. So only my patch needs review by anyone but me.

[kcrisman]

This looks okay, but I'm not sure how to test the documentation building and looking right. Also, just for my information, when do we need r""" and when is """ sufficient? Also, apparently the input for init goes in the class definition - is that right? My apologies, I didn't realize that.

[mvngu]

Replying to kcrisman:

This looks okay, but I'm not sure how to test the documentation building and looking right.

A quick-and-dirty way is to rebuild as follows from SAGE_ROOT:

./sage -b main
./sage -docbuild reference html

If you really want to be thorough, you could delete the whole output directory resulting from building the Sage documentation and then rebuild the whole reference manual again. This would take much longer than the above quick-and-dirty way, but it sure is more thorough. From SAGE_ROOT, do:

rm -rf devel/sage-main/doc/output/
./sage -b main
./sage -docbuild reference html

Also, just for my information, when do we need r""" and when is """ sufficient?

We need r""" when the docstring contains LaTeX escapes, i.e. LaTeX macros that start with a backslash character. In most other cases, """ is sufficient. For example, if your docstring contains something like

\sin(x)^2 + \cos(x)^2 = 1

then your docstring must be delimited with r""". For safety, I always use r""".

Also, apparently the input for init goes in the class definition - is that right?

At the moment, that is the case because docstrings for methods and functions whose names start with an underscore don't show up on the reference manual. So full documentation for the constructor __init__ are recommended to be in the class docstring. That way, documentation relating to the constructor, including its input and output documentation, shows up on the reference manual.

[kcrisman]

Okay, looks great and still passes tests.