#7477: Matroids
----------------------------------------------------+-----------------------
Reporter: ncohen | Owner: jkantor
Type: enhancement | Status:
needs_review
Priority: major | Milestone: sage-5.10
Component: combinatorics | Resolution:
Keywords: | Work issues:
Report Upstream: N/A | Reviewers:
Authors: Stefan van Zwam, Rudi Pendavingh | Merged in:
Dependencies: | Stopgaps:
----------------------------------------------------+-----------------------
Comment (by rbeezer):
I spent a good chunk of the afternoon looking over the documentation and
wrestling with `intersphinx`.
Following are all pretty routine, though maybe the messages from
exceptions needs discussion. Second post is about more mysterious stuff.
I'm doing
{{{
sage -docbuild reference html
}}}
and might turn to PDF output once this is settled. I'd be happy to ride
herd on documentation as part of a group review. By and large, it looks
excellent - I like many of the extras, like a discussion on subclassing
and accurate synopses and lists at the top of modules. Nits:
(1) Set up code in the small patch all looks routine to my eye (except see
next post). I have some experience with this, but will not say I am
expert at it, so a second look is probably in order. (Interesting to see
how little is actually required to add in a whole new field.) On the
downside, having "matroid" at the top level is now going to make it harder
to auto-complete the top-level "matrix" at the command line. ;-)
(2) In "Creating mew Matroid subclasses": "For incidental use, the
!RankMatroid subclass." needs another "use"?
(3) In documentation of matroid.is_isomorphism() the EXAMPLES all have an
extra indent. Again with matroid.minor, matroid.equals. You might troll
for more of these across all modules.
(4) I see "!MatroidError" instances in the documentation, specifically
here at matroid.max_independent. Is there a precedent for custom
exceptions elsewhere in Sage? More commonly errors are !TypeError or
!ValueError it seems to me. (Yes, PEP8 says differently.) And I find the
"Problem with a matroid operation:" redundant. I believe it is a Python
convention to have error messages begin with a lower case, to follow the
colon (but cannot find a reference for this).
I'd be inclined to replace
{{{
MatroidError: Problem with a matroid operation: 'Input is not a subset of
the groundset.'
}}}
with something like
{{{
ValueError: 'input set is not a subset of the groundset.'
}}}
Even better is to repeat the problem input in the error message. Here:
{{{
ValueError: 'input set ['x'] is not a subset of the groundset.'
}}}
There is usually enough context provided automatically, but echioing the
bad input is often very helpful. Also consider making the text of error
messages somewhat unique, so that searches will land a user at the right
place in the reference manual.
(5) Apparently-minor documentation warnings follow. Should be trivial to
fix.
{{{
[matroids ] /sage/sage-5.10.beta4/local/lib/python2.7/site-
packages/sage/matroids/catalog.py:docstring of
sage.matroids.catalog.NonVamos:3: WARNING: Inline interpreted text or
phrase reference start-string without end-string.
[matroids ] /sage/sage-5.10.beta4/local/lib/python2.7/site-
packages/sage/matroids/catalog.py:docstring of
sage.matroids.catalog.P8pp:1: WARNING: Inline interpreted text or phrase
reference start-string without end-string.
[matroids ] /sage/sage-5.10.beta4/local/lib/python2.7/site-
packages/sage/matroids/catalog.py:docstring of
sage.matroids.catalog.P8pp:1: WARNING: Inline interpreted text or phrase
reference start-string without end-string.
[matroids ] <autodoc>:0: WARNING: Bullet list ends without a blank line;
unexpected unindent.
}}}
--
Ticket URL: <http://trac.sagemath.org/sage_trac/ticket/7477#comment:31>
Sage <http://www.sagemath.org>
Sage: Creating a Viable Open Source Alternative to Magma, Maple, Mathematica,
and MATLAB
--
You received this message because you are subscribed to the Google Groups
"sage-trac" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to [email protected].
To post to this group, send email to [email protected].
Visit this group at http://groups.google.com/group/sage-trac?hl=en.
For more options, visit https://groups.google.com/groups/opt_out.
