#5330: [with patch, needs review] Move the docs over to the main repository
---------------------------+------------------------------------------------
Reporter: mhansen | Owner: mhansen
Type: enhancement | Status: new
Priority: major | Milestone: sage-3.4
Component: documentation | Keywords:
---------------------------+------------------------------------------------
Comment(by cwitty):
OK, this is going to be a long and complicated review :)
I'm attaching a reviewer patch that fixes a few problems (makes doctests
in builder.py pass, gives builder.py a better help message than "Help
message", removes a module reference from the documentation that was in
there twice (which was actually a carryover from the old documentation)).
With this patch, I give a positive review to doc/common (the python code
behind "sage -docbuild").
I believe that the non-automatically-generated portions of the new
reference manual are essentially the same as the corresponding parts of
the old reference manual, with some very important exceptions. (I did
notice some errors that were carried over from the original manual, but
I'll file separate tickets for those, with patches, so as not to cloud the
issue on this ticket.)
The exceptions are that several sections (and one entire chapter) got
(accidentally?) omitted from the new reference manual. These include:
the GPL
sage/schemes/readme.py
and the entire Structures chapter
(sage/structure/{sage_object,parent_gens,formal_sum,factorization,element,mutability,sequence,
parent,coerce,coerce_actions,coerce_maps}, sage/sets/{set,primes}).
I'd still vote in favor of applying this patch (and the rest of the
sphinxification patches), under the assumption that these missing sections
will get re-added to the reference manual quickly. So: positive review
for doc/en/reference. Except:
There's a lot of junk in doc/en/reference/utils included in this patch
(perhaps accidentally?). Mixed in with the junk are, I think, the tools
mhansen used to convert the reference manual. It would be nice to have
the junk at least minimally sorted (remove the files that are totally
useless, add a four- or five-line comment at the top of each useful file
explaining what it does and how to use it). With the junk mixed in, that
lowers the value of the directory considerably. But still, it's nice to
have mhansen's tools, so a weak positive review on doc/en/reference/utils
even in its current state.
And as I mentioned in my previous comment, I did not review doc/fr/*, or
doc/en/* except for the reference manual. I did notice, though, that
doctests in some of the not-previously-doctested files fail:
{{{
The following tests failed:
sage -t "devel/sage/doc/en/bordeaux_2008/nf_introduction.rst"
sage -t "devel/sage/doc/en/tutorial/distributed.rst"
sage -t "devel/sage/doc/fr/tutorial/tour_rings.rst"
sage -t "devel/sage/doc/fr/tutorial/tour_numtheory.rst"
}}}
I did not look into the problems at all.
--
Ticket URL: <http://trac.sagemath.org/sage_trac/ticket/5330#comment:3>
Sage <http://sagemath.org/>
Sage - Open Source Mathematical Software: Building the Car Instead of
Reinventing the Wheel
--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the Google Groups
"sage-trac" group.
To post to this group, send email to [email protected]
To unsubscribe from this group, send email to
[email protected]
For more options, visit this group at
http://groups.google.com/group/sage-trac?hl=en
-~----------~----~----~----~------~----~------~--~---
