Sage: Ticket #5911: greatly improve the documentation one gets from Graph?
https://trac.sagemath.org/ticket/5911
<p>
Imagine a new user who wants to create a graph. They do <code>Graph?</code> and they get (in order):
</p>
<ol><li>Two pages of parameters, which they can't possibly read through.
</li></ol><ol start="2"><li>The first *page* of examples all involve networkx (they think -- huh?) and starts like this.
</li></ol><pre class="wiki">
EXAMPLES: We illustrate the first six input formats (the other two
involve packages that are currently not standard in Sage):
#. A NetworkX XGraph::
sage: import networkx
sage: g = networkx.XGraph({0:[1,2,3], 2:[4]})
sage: Graph(g)
Graph on 5 vertices
....
</pre><p>
I propose:
</p>
<ol><li>Putting a few simple straightforward examples (which is all most users need) right *before* the INPUT: block.
</li></ol><ol start="2"><li>Moving any mention of networkx lower in the lists, e.g., when defining the data input, don't put networkx first, and when documenting things later with examples, don't put networkx first.
</li></ol><ol start="3"><li>That one can do "graphs.<tab>" and get constructors for any family of graphs should be noted clearly and prominently, also before the INPUT: block. This is not even noted anywhere right now, though it is used in two examples.
</li></ol><p>
The above are all easy changes, I think.
</p>
en-usSagehttps://trac.sagemath.org/chrome/site/logo_sagemath_trac.png
https://trac.sagemath.org/ticket/5911
Trac 1.1.6jasonMon, 27 Apr 2009 15:59:15 GMT
https://trac.sagemath.org/ticket/5911#comment:1
https://trac.sagemath.org/ticket/5911#comment:1
<p>
+1!
</p>
<p>
So you're saying that Graph? should be something like graphs?
</p>
TicketncohenMon, 03 Aug 2009 17:09:13 GMT
https://trac.sagemath.org/ticket/5911#comment:2
https://trac.sagemath.org/ticket/5911#comment:2
<p>
I began to write something, as I thought nobody was working on it seeing that last message was posted 3 months ago ;-)
</p>
<p>
What I have written is just a short introduction meant for user <strong>really</strong> unfamiliar with graphs in Sage and in general.. I expect a lot of critics from you, and I will change it accordingly, but I have spent much time in the past days trying to explain how to use graphs in Sage to some of my friends that I thought the best way may be to directly document this section... Tell me what you would change to this :
</p>
<p>
<a class="ext-link" href="http://www-sop.inria.fr/members/Nathann.Cohen/infograph.py"><span class="icon"></span>http://www-sop.inria.fr/members/Nathann.Cohen/infograph.py</a>
</p>
TicketncohenWed, 05 Aug 2009 11:56:09 GMTsummary changed
https://trac.sagemath.org/ticket/5911#comment:3
https://trac.sagemath.org/ticket/5911#comment:3
<ul>
<li><strong>summary</strong>
changed from <em>greatly improve the documentation one gets from Graph?</em> to <em>[with draft, needs critics] greatly improve the documentation one gets from Graph?</em>
</li>
</ul>
TicketrlmWed, 05 Aug 2009 16:30:36 GMT
https://trac.sagemath.org/ticket/5911#comment:4
https://trac.sagemath.org/ticket/5911#comment:4
<p>
Nathann,
</p>
<p>
This looks pretty good. Can you change the examples a bit, though? For example, a lot of the docstrings about creating graphs from graph6 strings include test cases where an error is triggered. As long as these failures are somewhere in the documentation, they're tested. Maybe the docs here should focus more on how to properly work with them. Also, you should get this into the appropriate place in <code>graph.py</code> and post it as an actual patch, so that e.g. we can post modifications and more people can pitch in to help. Finally, I believe that a few code blocks at the beginning need the <code>::</code> and indentation, e.g.:
</p>
<pre class="wiki"> If you want to see what they look like, begin this way :
sage: g=graphs.PetersenGraph()
sage: g.plot()
or
sage: g=graphs.ChvatalGraph()
sage: g.plot()
</pre>
TicketncohenWed, 05 Aug 2009 18:37:55 GMT
https://trac.sagemath.org/ticket/5911#comment:5
https://trac.sagemath.org/ticket/5911#comment:5
<p>
Hello !
</p>
<p>
Several questions :
</p>
<ul><li>I agree that way to raise errors and exceptions have no real place in Graph?. Where should I put them ? In the looooooooong docstring at the beginning of file graph.py ?
</li></ul><ul><li>I do not understand their purpose anyway. There or elsewhere O_o
</li></ul><ul><li>No problem with '::' as I can see some occurences of them in this docstring... What are they meant to do, though ? ;-)
</li></ul><ul><li>I did not post a patch thinking it would be much easier to read it this way as it seemed far from a final version. The next one will be a patch ;-)
</li></ul>
TicketncohenMon, 17 Aug 2009 15:06:14 GMT
https://trac.sagemath.org/ticket/5911#comment:6
https://trac.sagemath.org/ticket/5911#comment:6
<p>
Here is the patch you requested.. Where do you think we should store these doctests you mentionned if not in this docstring ?
</p>
TicketncohenMon, 17 Aug 2009 15:08:24 GMTattachment set
https://trac.sagemath.org/ticket/5911
https://trac.sagemath.org/ticket/5911
<ul>
<li><strong>attachment</strong>
set to <em>doc_graph.patch</em>
</li>
</ul>
TicketncohenMon, 17 Aug 2009 15:09:15 GMTsummary changed
https://trac.sagemath.org/ticket/5911#comment:7
https://trac.sagemath.org/ticket/5911#comment:7
<ul>
<li><strong>summary</strong>
changed from <em>[with draft, needs critics] greatly improve the documentation one gets from Graph?</em> to <em>[with draft, needs review] greatly improve the documentation one gets from Graph?</em>
</li>
</ul>
TicketncohenMon, 17 Aug 2009 15:09:43 GMTsummary changed
https://trac.sagemath.org/ticket/5911#comment:8
https://trac.sagemath.org/ticket/5911#comment:8
<ul>
<li><strong>summary</strong>
changed from <em>[with draft, needs review] greatly improve the documentation one gets from Graph?</em> to <em>[with patch, needs review] greatly improve the documentation one gets from Graph?</em>
</li>
</ul>
TicketrlmWed, 26 Aug 2009 18:36:33 GMTsummary changed
https://trac.sagemath.org/ticket/5911#comment:9
https://trac.sagemath.org/ticket/5911#comment:9
<ul>
<li><strong>summary</strong>
changed from <em>[with patch, needs review] greatly improve the documentation one gets from Graph?</em> to <em>[with patch, needs work] greatly improve the documentation one gets from Graph?</em>
</li>
</ul>
<p>
I've added some editing in a second patch, and I'd like to give this a positive review, but the documentation for <code>DiGraph?</code> suffers from the same fault, and I would feel less guilty if this ticket addressed that as well.
</p>
TicketrlmWed, 26 Aug 2009 18:37:58 GMTattachment set
https://trac.sagemath.org/ticket/5911
https://trac.sagemath.org/ticket/5911
<ul>
<li><strong>attachment</strong>
set to <em>trac_5911-editing.patch</em>
</li>
</ul>
<p>
apply on top of doc_graph.patch
</p>
TicketncohenWed, 26 Aug 2009 19:40:54 GMT
https://trac.sagemath.org/ticket/5911#comment:10
https://trac.sagemath.org/ticket/5911#comment:10
<p>
What about a good old : "cf. Graph" (or a plain copy of Graph?), as it is exactly the same ? <sup></sup>;
</p>
<p>
We could just write a list of the functions of <a class="missing wiki">DiGraph?</a> that are unaavailable in Graph, couldn't we ?
</p>
TicketncohenSat, 03 Oct 2009 09:32:18 GMT
https://trac.sagemath.org/ticket/5911#comment:11
https://trac.sagemath.org/ticket/5911#comment:11
<p>
Still around ? ;-)
</p>
TicketrlmThu, 08 Oct 2009 16:38:03 GMT
https://trac.sagemath.org/ticket/5911#comment:12
https://trac.sagemath.org/ticket/5911#comment:12
<p>
Replying to <a class="ticket" href="https://trac.sagemath.org/ticket/5911#comment:10" title="Comment 10">ncohen</a>:
</p>
<blockquote class="citation">
<p>
What about a good old : "cf. Graph" (or a plain copy of Graph?), as it is exactly the same ? <sup></sup>;
</p>
<p>
We could just write a list of the functions of <a class="missing wiki">DiGraph?</a> that are unaavailable in Graph, couldn't we ?
</p>
</blockquote>
<p>
Imagine you have never used Sage before, and you really really like <a class="missing wiki">DiGraphs?</a>. So one of the first things you do in Sage, aside from <code>2+2</code> or <code>factor(factorial(12))</code>, is type <code>DiGraph?</code>. I think there are such (potential) users out there, and the documentation there should be independently helpful. Certainly a reference to <code>Graph?</code> would be appropriate, but the docs you get from <code>DiGraph?</code> should also be self-contained and helpful.
</p>
TicketncohenThu, 08 Oct 2009 16:47:16 GMT
https://trac.sagemath.org/ticket/5911#comment:13
https://trac.sagemath.org/ticket/5911#comment:13
<p>
Then a plain copy could do, couldn't it ? Plus some <a class="missing wiki">DiGraph?</a>-specific functions .. ;-)
</p>
TicketrlmThu, 08 Oct 2009 16:50:14 GMT
https://trac.sagemath.org/ticket/5911#comment:14
https://trac.sagemath.org/ticket/5911#comment:14
<p>
Replying to <a class="ticket" href="https://trac.sagemath.org/ticket/5911#comment:13" title="Comment 13">ncohen</a>:
</p>
<blockquote class="citation">
<p>
Then a plain copy could do, couldn't it ?
</p>
</blockquote>
<p>
Essentially, yes, subject to <code>s/Graph/DiGraph</code>.
</p>
<blockquote class="citation">
<p>
Plus some <a class="missing wiki">DiGraph?</a>-specific functions .. ;-)
</p>
</blockquote>
<p>
For the <a class="missing wiki">DiGraph?</a> fans!
</p>
TicketncohenTue, 13 Oct 2009 08:15:04 GMTstatus, summary changed
https://trac.sagemath.org/ticket/5911#comment:15
https://trac.sagemath.org/ticket/5911#comment:15
<ul>
<li><strong>status</strong>
changed from <em>needs_work</em> to <em>needs_review</em>
</li>
<li><strong>summary</strong>
changed from <em>[with patch, needs work] greatly improve the documentation one gets from Graph?</em> to <em>greatly improve the documentation one gets from Graph?</em>
</li>
</ul>
<p>
New version with an updated <a class="missing wiki">DiGraph?</a> section. Some problem, still : when running a sage -t on graph.py, Python does not like to see g.diameter ? which is mentioned in the doc.
</p>
<p>
Do you know how to fix this ?
</p>
<p>
This new patch is a flattened version of the previous ones, plus the updates. Only this one should be applied.
</p>
<p>
Nathann
</p>
TicketncohenTue, 13 Oct 2009 08:15:43 GMTattachment set
https://trac.sagemath.org/ticket/5911
https://trac.sagemath.org/ticket/5911
<ul>
<li><strong>attachment</strong>
set to <em>trac_5911.patch</em>
</li>
</ul>
TicketncohenTue, 13 Oct 2009 08:22:07 GMT
https://trac.sagemath.org/ticket/5911#comment:16
https://trac.sagemath.org/ticket/5911#comment:16
<p>
Hmmm.. This -- should -- have been a flattened version of all the patches, though it is not and I wonder why. This patch needs doc_graph.patch to be applied first, and contains trac_5911-editing.patch. So only doc_graph.patch and this patch should be applied.
</p>
<p>
I tried to build a real flattened version, but for some reason I can not O_o
</p>
<p>
Nathann
</p>
TicketmvnguWed, 28 Oct 2009 14:59:49 GMTattachment set
https://trac.sagemath.org/ticket/5911
https://trac.sagemath.org/ticket/5911
<ul>
<li><strong>attachment</strong>
set to <em>trac_5911-reviewer.patch</em>
</li>
</ul>
<p>
reviewer patch
</p>
TicketmvnguWed, 28 Oct 2009 15:02:37 GMT
https://trac.sagemath.org/ticket/5911#comment:17
https://trac.sagemath.org/ticket/5911#comment:17
<p>
I have attached a reviewer patch. So patches should be applied in the following order:
</p>
<ol><li><code>doc_graph.patch</code>
</li><li><code>trac_5911.patch</code>
</li><li><code>trac_5911-reviewer.patch</code>
</li></ol><p>
The reviewer patch fixes some typos and grammar issues. It also adjusts some examples to prevent doctest failures. Only my patch needs to be reviewed.
</p>
TicketmhansenThu, 05 Nov 2009 01:26:21 GMTstatus changed; reviewer, author set
https://trac.sagemath.org/ticket/5911#comment:18
https://trac.sagemath.org/ticket/5911#comment:18
<ul>
<li><strong>status</strong>
changed from <em>needs_review</em> to <em>positive_review</em>
</li>
<li><strong>reviewer</strong>
set to <em>Minh Van Nguyen, Mike Hansen</em>
</li>
<li><strong>author</strong>
set to <em>Nathann Cohen</em>
</li>
</ul>
<p>
Looks good to me.
</p>
TicketmhansenThu, 05 Nov 2009 01:33:06 GMTstatus, reviewer changed; resolution, merged set
https://trac.sagemath.org/ticket/5911#comment:19
https://trac.sagemath.org/ticket/5911#comment:19
<ul>
<li><strong>status</strong>
changed from <em>positive_review</em> to <em>closed</em>
</li>
<li><strong>reviewer</strong>
changed from <em>Minh Van Nguyen, Mike Hansen</em> to <em>Robert Miller, Minh Van Nguyen, Mike Hansen</em>
</li>
<li><strong>resolution</strong>
set to <em>fixed</em>
</li>
<li><strong>merged</strong>
set to <em>sage-4.2.1.alpha0</em>
</li>
</ul>
Ticket