#8513: Including documentation in the reference manual for some files related to
graph theory
------------------------------------------------------+---------------------
Reporter: abmasse | Owner: rlm
Type: defect | Status:
needs_review
Priority: minor | Milestone: sage-4.4
Component: graph theory | Keywords:
documentation, graph theory
Author: Alexandre Blondin Massé, Nathann Cohen | Upstream: N/A
Reviewer: Minh Van Nguyen | Merged:
Work_issues: |
------------------------------------------------------+---------------------
Changes (by newvalueoldvalue):
* reviewer: => Minh Van Nguyen
* author: => Alexandre Blondin Massé, Nathann Cohen
Comment:
Replying to [comment:9 jhpalmieri]:
> I don't know much about graph theory, but is there any sense to the
current order in the reference manual?
No, I don't think so. The current organization is a mess.
[[BR]][[BR]]
> Wouldn't it make more sense for {{{graph}}} to come first, for example,
rather than {{{cliquer}}}?
Yes. The current organization of the graph theory modules, as they appear
in the reference manual, is rather unusual. For example, the interface to
cliquer appears as the very first link. One would expect something along
the following line to be more natural:
* undirected graph
* digraph
* generic graph
* applications of graph theory
* fast compiled graph
* etc.
I have uploaded a reviewer patch that does something about this. With my
reviewer patch, the organization of the graph theory modules should be
more systematic.
[[BR]][[BR]]
> I don't think alphabetical is the right approach: someone who wants to
know about graphs in Sage may very well start at the first link in the
"Graph Theory" chapter. (It might be even better to have an introductory
section in the file devel/sage/doc/en/reference/graphs.rst (like
matrices.rst, for example). That probably belongs on another ticket,
though.)
Nod. This needs to wait for another ticket.
[[BR]][[BR]]
After applying [http://trac.sagemath.org/sage_trac/attachment/ticket/8513
/trac_8513_graph_theory_documentation-abm.patch
trac_8513_graph_theory_documentation-abm.patch] and
[http://trac.sagemath.org/sage_trac/attachment/ticket/8513
/trac_8513_graph_theory_documentation-smallfixes.patch
trac_8513_graph_theory_documentation-smallfixes.patch], I then rebuilt the
whole Sage documentation. A long doctest of the whole Sage library
resulted in the following failure:
{{{
sage -t -long devel/sage-main/sage/misc/sagedoc.py
**********************************************************************
File "/dev/shm/mvngu/sandbox/sage-4.3.5-8513-graph-doc/devel/sage-
main/sage/misc/sagedoc.py", line 892:
sage: len(search_doc('tree', whole_word=True,
interact=False).splitlines()) < 100
Expected:
True
Got:
False
}}}
This is due to adding two new files to the reference manual that happen to
be about graph theory, hence the above search returns more matches for the
word "tree". My reviewer patch should fix this doctest failure. It needs
reviewing by anyone but me. I'm happy with both abmasse and ncohen's
patches. Apply patches in the following order:
1. [http://trac.sagemath.org/sage_trac/attachment/ticket/8513
/trac_8513_graph_theory_documentation-abm.patch
trac_8513_graph_theory_documentation-abm.patch]
1. [http://trac.sagemath.org/sage_trac/attachment/ticket/8513
/trac_8513_graph_theory_documentation-smallfixes.patch
trac_8513_graph_theory_documentation-smallfixes.patch]
1.
[http://trac.sagemath.org/sage_trac/attachment/ticket/8513/trac_8513-reviewer.patch
trac_8513-reviewer.patch]
--
Ticket URL: <http://trac.sagemath.org/sage_trac/ticket/8513#comment:11>
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 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.
