[with patch, needs work] convert sage.rings.* docstrings to Sphinx

[mhansen]

Patch at  http://sage.math.washington.edu/home/mhansen/trac_4925.patch

[robertwb]

 http://sage.math.washington.edu/home/mhansen/sage/devel/sage/doc/output/html/en/reference/sage/rings/number_field/number_field.html has some weirdness going on with the line "We create the 7th cyclotomic field \mathbb{Q}(\zeta_7) with the default generator name."

[cwitty]

I've reviewed the first 22% of this patch (I finished integer.pyx, and have not started integer_mod.pyx). Here's the issues I've found so far:

I'm working mostly from the patch source, but occasionally also checking the rendered result, at 
http://sage.math.washington.edu/home/mhansen/sage/devel/sage-old/doc/output/html/en/reference/sage/rings/...
(references to the rendered output refer to this particular version as 
of 2009-01-19)

========== arith.py

the docstring for bernoulli screwed up the INPUT list: "algorithm:" is
the name of an input, and 'default' through 'bernmm' are possible
values for that input

The docstring for bernoulli (in the case 'default') lost a '<' and a
'>' (one each)

in the docstring for bernoulli, the indentation of the tests in TESTS is bad:
three tests are indented relative to the others

in the docstring for bernoulli, it changes a "\note{...}" to 
".. note:", but the result seems not to show up in the formatted manual at all

in the docstring for factorial (INPUT section), 'gmp' and 'pari' are
possible values for algorithm, not separate arguments

in the docstring for is_prime (INPUT section), 0, 1, and 2 should be a
bulleted sublist of the ``flag`` item

in the docstring for is_pseudoprime (INPUT section), 0 and "> 0" should be 
a sublist of ``flag``.  (And the '>' is missing from "> 0".)

in the docstring for is_prime_power (INPUT section), 0, 1, and 2
should be subitems

docstring for previous_prime is missing two '<'

docstring for random_prime is missing two '<' (in the summary section)
and one '>' (in INPUT section)

docstring for xlcm is missing two '|' (in the summary section)

docstring for rational_reconstruction is missing four '<' (one in summary,
one in output section, two in algorithm discussion)

docstring for rational_reconstruction has mangled input section
(should be nested lists, not a single paragraph); output section
should be separate from input section

docstring for mqrr_rational_reconstruction has mangled input/output sections
(should be separate sections, not a single paragraph); input/output section
missing lots of '<' and '>'

trial_division docstring is missing two '<' (one in summary, one in
output section)

trial_division docstring INPUT section is mangled: should have two
items (``n`` and ``bound``)

odd_part docstring lost the "\code{...}" wrapper from $v =
\code{valuation(n,2)}$

is_squarefree docstring is missing '>'

Euler_phi docstring is missing two '<'

kronecker_symbol docstring is missing '|'

legendre_symbol docstring is missing '|'

hilbert_symbol INPUT section: 'pari', 'direct', 'all' should be subitems of
``algorithm``

falling_factorial, rising_factorial INPUT sections: I like the
previous location of the "or"; can we do something to make it more
clear that it's either the first two items or the third item?

========== complex_double.pyx

docstring of method gen: the word "EXAMPLES::" should be on a separate line 
from the summary

docstring of __pow__: "We raise to symbolic powers" section: indentation
of examples is inconsistent

========== complex_number.pyx

docstring of __getitem__: INPUT section is mangled (i=0, i=1 should be a 
sublist, EXAMPLES should be a separate section)

docstring of str: INPUTS section is mangled: should be a list

docstring of __rdiv__: INPUTS section is mangled: should be a list

docstring of eta: EXAMPLES section: "First we compute..." should be a separate
paragraph from the word EXAMPLES

docstring of dilog: "EXAMPLES:" should be a paragraph of its own, not part of
the summary

docstring of log: missing two '<'

docstring of create_ComplexNumber: missing '>' (INPUT section, under ``pad``)

========== finite_field.py

docstring of class FiniteFieldFactory: missing '<' 
(INPUT section, under ``elem_cache``)

========== finite_field_element.py

docstring of polynomial: "EXAMPLES:" should be a paragraph of its own,
not joined with "The default variable is a::"

========== fraction_field.py

AUTHOR section of file docstring: the patch adds Burcin Erocal as an
author.

========== homset.py

"TEST: We test pickling of a homset..." should be two separate paragraphs

========== ideal.py

many docstrings: the word "EXAMPLES:" should be a separate paragraph,
not joined with the next paragraph (same for TESTS:)

========== infinity.py

EXAMPLES: should be separate paragraph, not merged with next paragraph

========== integer.pyx

On the second line of the file, m`\mathbb{Z}` has an extra 'm'

in AUTHORS section, Didier's email address was removed

_digits_internal method: "Parameters:" should become "INPUT:", and should
have a list instead of a muddled paragraph.  Also, this section is missing
two '<' under power_index

__pow__: missing '^' in 
"For consistency with Python and MPFR, 00 is defined to be 1 in"

nth_root: missing '>' in INPUT section, under ``n``

exact_root: missing '>' in INPUT section

is_prime_power: INPUT section: 0, 1, 2 should be sublist of ``flag``

I'll probably return to reviewing this patch later this week; if somebody else starts to review it before I get around to it, please add a comment to this ticket so we don't duplicate work.

[cwitty]

I've attached a patch that fixes the problems I found in the remaining 78% of the file (my patch does not fix problems that I reported in the above comment).

I now suspect that you removed email addresses from AUTHOR blocks (in polynomial/multi_polynomial_ideal.py and real_mpfr.pyx) deliberately. If so,

1) I would have preferred that this be a separate change; having substantive changes mixed in with the huge LaTeX->ReST patch makes it more difficult to review; and

2) you missed some (for example, pbori.pyx still has email addresses).

Once the issues from the above comment are fixed, and we decide what to do about the email addresses, this will be a positive review for the original patch. Probably somebody should review my reviewer patch, though, since it's so big.

[mabshoff]

Merged in Sage 3.4.alpha0.

Cheers,

Michael