Sage: Ticket #12810: Broken links in the documentation of graph/ files
https://trac.sagemath.org/ticket/12810
<p>
Florent [1] added a nice --warn-links argument for -docbuild which screams immediately when a Sphinx link does not work properly (Sphinx does not find where the link is pointing to), and the option is not enabled by default because, of course, there are *MANY* such links in our documentation <code>:-)</code>
</p>
<p>
This patch fixes those links in the Graph database (those that *could* be fixed, actually), like <a class="closed ticket" href="https://trac.sagemath.org/ticket/12767" title="defect: Clean up dead links in sage/rings/number_field documentation (closed: fixed)">#12767</a> already does for sage/rings/number_field.
</p>
<p>
[1] <a class="ext-link" href="http://groups.google.com/forum/?fromgroups#!topic/sage-devel/c5cdBO3hvKM"><span class="icon"></span>http://groups.google.com/forum/?fromgroups#!topic/sage-devel/c5cdBO3hvKM</a>
</p>
<p>
Nathann
</p>
<hr />
<p>
Apply <a class="attachment" href="https://trac.sagemath.org/attachment/ticket/12810/trac_12810-rebased.patch" title="Attachment 'trac_12810-rebased.patch' in Ticket #12810">trac_12810-rebased.patch</a><a class="trac-rawlink" href="https://trac.sagemath.org/raw-attachment/ticket/12810/trac_12810-rebased.patch" title="Download"></a>.
</p>
en-usSagehttps://trac.sagemath.org/chrome/site/logo_sagemath_trac.png
https://trac.sagemath.org/ticket/12810
Trac 1.1.6ncohenThu, 05 Apr 2012 10:28:20 GMTstatus, description changed
https://trac.sagemath.org/ticket/12810#comment:1
https://trac.sagemath.org/ticket/12810#comment:1
<ul>
<li><strong>status</strong>
changed from <em>new</em> to <em>needs_review</em>
</li>
<li><strong>description</strong>
modified (<a href="/ticket/12810?action=diff&version=1">diff</a>)
</li>
</ul>
TicketdavidloefflerThu, 05 Apr 2012 11:17:35 GMTstatus changed
https://trac.sagemath.org/ticket/12810#comment:2
https://trac.sagemath.org/ticket/12810#comment:2
<ul>
<li><strong>status</strong>
changed from <em>needs_review</em> to <em>needs_work</em>
</li>
</ul>
<p>
I still get a bunch of warnings when I install this and rebuild the docs:
</p>
<pre class="wiki">masiao@fermat:/storage/masiao/sage-5.0.beta12/devel/sage-12810$ sage -docbuild --warn-links reference html
sphinx-build -b html -d /storage/masiao/sage-5.0.beta12/devel/sage/doc/output/doctrees/en/reference -n /storage/masiao/sage-5.0.beta12/devel/sage/doc/en/reference /storage/masiao/sage-5.0.beta12/devel/sage/doc/output/html/en/reference
Running Sphinx v1.1.2
loading pickled environment... done
loading intersphinx inventory from /storage/masiao/sage-5.0.beta12/devel/sage/doc/common/python.inv...
building [html]: targets for 9 source files that are out of date
updating environment: 1 added, 9 changed, 0 removed
reading sources... [100%] sage/graphs/trees
docstring of sage.graphs.base.c_graph:12: WARNING: Bullet list ends without a blank line; unexpected unindent.
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] sage/graphs/trees
<autodoc>:1: WARNING: py:class reference target not found: sage.graphs.base.graph_backends.GenericGraphBackend
/storage/masiao/sage-5.0.beta12/devel/sage/doc/en/reference/sage/graphs/generic_graph.rst:11: WARNING: py:class reference target not found: sage.graphs.generic_graph_pyx.GenericGraph_pyx
/storage/masiao/sage-5.0.beta12/local/lib/python2.7/site-packages/sage/graphs/graph_latex.py:docstring of sage.graphs.graph_latex.GraphLatex.get_option:9: WARNING: py:data reference target not found: __graphlatex_options
/storage/masiao/sage-5.0.beta12/local/lib/python2.7/site-packages/sage/graphs/graph_latex.py:docstring of sage.graphs.graph_latex.GraphLatex.latex:3: WARNING: py:meth reference target not found: sage.graphs.generic_graph.GenericGraph._latex_
/storage/masiao/sage-5.0.beta12/local/lib/python2.7/site-packages/sage/graphs/graph_latex.py:docstring of sage.graphs.graph_latex.GraphLatex.set_option:11: WARNING: py:data reference target not found: sage.graphs.graph_latex.GraphLatex.__graphlatex_options
writing additional files... genindex py-modindex search
copying images... [100%] sage/graphs/../../media/heawood-graph-latex.png
copying static files... done
dumping search index... done
dumping object inventory... done
build succeeded, 6 warnings.
Build finished. The built documents can be found in /storage/masiao/sage-5.0.beta12/devel/sage/doc/output/html/en/reference
</pre><p>
Five of these are "link not found" warnings that presumably weren't easily fixable, but one of them is a genuine formatting error which would have come up even without --warn-links, and we can't have that -- sorry!
</p>
TicketncohenThu, 05 Apr 2012 11:57:42 GMTstatus changed
https://trac.sagemath.org/ticket/12810#comment:3
https://trac.sagemath.org/ticket/12810#comment:3
<ul>
<li><strong>status</strong>
changed from <em>needs_work</em> to <em>needs_review</em>
</li>
</ul>
<blockquote class="citation">
<p>
Five of these are "link not found" warnings that presumably weren't easily fixable, but one of them is a genuine formatting error which would have come up even without --warn-links, and we can't have that -- sorry!
</p>
</blockquote>
<p>
Oh My, but you are totally right ! <code>:-)</code>
</p>
<p>
This was a stupid alignment problem. Patch updated <code>:-)</code>
</p>
<p>
Nathann
</p>
TicketncohenFri, 06 Apr 2012 11:34:07 GMT
https://trac.sagemath.org/ticket/12810#comment:4
https://trac.sagemath.org/ticket/12810#comment:4
<p>
(same patch, I just added two files to the Graph documentation and removed some trailing whitespaces in a *very* stable file)
</p>
TicketncohenFri, 06 Apr 2012 12:03:17 GMT
https://trac.sagemath.org/ticket/12810#comment:5
https://trac.sagemath.org/ticket/12810#comment:5
<p>
(plus some semicolumns because, of course, the files were not properly formatted <code>:-P</code>)
</p>
TicketkcrismanTue, 29 May 2012 05:51:54 GMTstatus changed; keywords, reviewer set
https://trac.sagemath.org/ticket/12810#comment:6
https://trac.sagemath.org/ticket/12810#comment:6
<ul>
<li><strong>status</strong>
changed from <em>needs_review</em> to <em>needs_work</em>
</li>
<li><strong>keywords</strong>
<em>sd40.5</em> added
</li>
<li><strong>reviewer</strong>
set to <em>Karl-Dieter Crisman</em>
</li>
</ul>
<p>
There remain
</p>
<pre class="wiki">/Users/.../sage-5.1.beta1/local/lib/python2.7/site-packages/sage/graphs/graph_latex.py:docstring of sage.graphs.graph_latex.GraphLatex.get_option:9: WARNING: py:data reference target not found: __graphlatex_options
/Users/.../sage-5.1.beta1/local/lib/python2.7/site-packages/sage/graphs/graph_latex.py:docstring of sage.graphs.graph_latex.GraphLatex.latex:3: WARNING: py:meth reference target not found: sage.graphs.generic_graph.GenericGraph._latex_
/Users/.../sage-5.1.beta1/local/lib/python2.7/site-packages/sage/graphs/graph_latex.py:docstring of sage.graphs.graph_latex.GraphLatex.set_option:11: WARNING: py:data reference target not found: sage.graphs.graph_latex.GraphLatex.__graphlatex_options
</pre><p>
Couldn't one just change the syntax to say
</p>
<pre class="wiki">``sage.graphs.graph_latex.GraphLatex.__graphlatex_options``
</pre><p>
instead of the following?
</p>
<pre class="wiki">:data:`sage.graphs.graph_latex.GraphLatex.__graphlatex_options`
</pre><p>
Something similar might be able to be said about
</p>
<pre class="wiki">:meth:`sage.graphs.generic_graph.GenericGraph._latex_`
</pre><p>
but then again maybe this is not worth the trouble. I still wish we had the "superreference" target for the docbuild, which included all underscore methods.
</p>
<p>
Also, we are trying to discourage double-underscore attributes. Such as <code>__graphlatex_options</code>. Could this be made single-underscore (perhaps in another ticket, if appropriate)?
</p>
<p>
More comments:
</p>
<ul><li>The doc looks wrong in the (short) tree.pyx - you'll see what I mean.
</li><li>The AUTHORS in matchpoly is indented too much.
</li><li>graph_plot.html can have trac <a class="closed ticket" href="https://trac.sagemath.org/ticket/10124" title="defect: Graph drawing has issues with edge labels (closed: fixed)">#10124</a> written as <code>:trac:`#10124`</code>, I think.
</li></ul><p>
All that said, it seems like it's pretty good overall.
</p>
TicketncohenTue, 29 May 2012 06:48:34 GMTstatus changed
https://trac.sagemath.org/ticket/12810#comment:7
https://trac.sagemath.org/ticket/12810#comment:7
<ul>
<li><strong>status</strong>
changed from <em>needs_work</em> to <em>needs_review</em>
</li>
</ul>
<p>
Hellooooooooooooooooo !!!
</p>
<blockquote class="citation">
<p>
Couldn't one just change the syntax to say
</p>
<pre class="wiki">``sage.graphs.graph_latex.GraphLatex.__graphlatex_options``
</pre></blockquote>
<p>
Done !!
</p>
<blockquote class="citation">
<p>
Also, we are trying to discourage double-underscore attributes. Such as <code>__graphlatex_options</code>. Could this be made single-underscore (perhaps in another ticket, if appropriate)?
</p>
</blockquote>
<p>
Hmmm.. I prefer to let the combinat guys deal with that, it may break code on their side.
</p>
<blockquote class="citation">
<ul><li>The doc looks wrong in the (short) tree.pyx - you'll see what I mean.
</li></ul></blockquote>
<p>
Oh, yeah. Columns.
</p>
<blockquote class="citation">
<ul><li>The AUTHORS in matchpoly is indented too much.
</li></ul></blockquote>
<p>
Done, done.
</p>
<blockquote class="citation">
<ul><li>graph_plot.html can have trac <a class="closed ticket" href="https://trac.sagemath.org/ticket/10124" title="defect: Graph drawing has issues with edge labels (closed: fixed)">#10124</a> written as <code>:trac:`#10124`</code>, I think.
</li></ul></blockquote>
<p>
That too.
</p>
<p>
Patch updated ! Thank you for the review <code>:-)</code>
</p>
<p>
Nathann
</p>
TicketncohenTue, 29 May 2012 06:48:51 GMTattachment set
https://trac.sagemath.org/ticket/12810
https://trac.sagemath.org/ticket/12810
<ul>
<li><strong>attachment</strong>
set to <em>trac_12810.patch</em>
</li>
</ul>
TicketkcrismanTue, 29 May 2012 07:13:03 GMTstatus changed
https://trac.sagemath.org/ticket/12810#comment:8
https://trac.sagemath.org/ticket/12810#comment:8
<ul>
<li><strong>status</strong>
changed from <em>needs_review</em> to <em>positive_review</em>
</li>
</ul>
<p>
Great. I'm uploading one rebased to Sage 5.1.beta1. I did get one weird error
</p>
<pre class="wiki"><autodoc>:1: WARNING: py:class reference target not found: sage.graphs.base.graph_backends.GenericGraphBackend
<autodoc>:1: WARNING: py:class reference target not found: sage.graphs.generic_graph_pyx.GenericGraph_pyx
</pre><p>
but I haven't got a clue where that comes from, given that there is no file associated with it, so I'm not going to worry about it.
</p>
TicketkcrismanTue, 29 May 2012 07:15:07 GMTdescription changed
https://trac.sagemath.org/ticket/12810#comment:9
https://trac.sagemath.org/ticket/12810#comment:9
<ul>
<li><strong>description</strong>
modified (<a href="/ticket/12810?action=diff&version=9">diff</a>)
</li>
</ul>
<p>
Patchbot: Apply <a class="attachment" href="https://trac.sagemath.org/attachment/ticket/12810/trac_12810-rebased.patch" title="Attachment 'trac_12810-rebased.patch' in Ticket #12810">trac_12810-rebased.patch</a><a class="trac-rawlink" href="https://trac.sagemath.org/raw-attachment/ticket/12810/trac_12810-rebased.patch" title="Download"></a>.
</p>
TicketncohenTue, 29 May 2012 07:16:35 GMT
https://trac.sagemath.org/ticket/12810#comment:10
https://trac.sagemath.org/ticket/12810#comment:10
<p>
Ohhh thank you !!
</p>
<p>
Actually I also get this error, and it looks like it is a temporary file created by Sphinx, but I really have no idea what should be changed to fix it.
</p>
<p>
Nathann
</p>
TicketjdemeyerTue, 29 May 2012 21:54:56 GMTstatus changed
https://trac.sagemath.org/ticket/12810#comment:11
https://trac.sagemath.org/ticket/12810#comment:11
<ul>
<li><strong>status</strong>
changed from <em>positive_review</em> to <em>needs_work</em>
</li>
</ul>
<p>
This patch conflicts with <a class="closed ticket" href="https://trac.sagemath.org/ticket/12605" title="defect: Change the default color of circle and ellipses, etc. back to be the ... (closed: fixed)">#12605</a>.
</p>
TicketkcrismanWed, 30 May 2012 03:59:05 GMTstatus changed
https://trac.sagemath.org/ticket/12810#comment:12
https://trac.sagemath.org/ticket/12810#comment:12
<ul>
<li><strong>status</strong>
changed from <em>needs_work</em> to <em>positive_review</em>
</li>
</ul>
<p>
Since I'm the one that generated the latest rebased patch as well as <a class="closed ticket" href="https://trac.sagemath.org/ticket/12605" title="defect: Change the default color of circle and ellipses, etc. back to be the ... (closed: fixed)">#12605</a>, I declare by fiat that this is the one that will be have priority. I'll rebase <a class="closed ticket" href="https://trac.sagemath.org/ticket/12605" title="defect: Change the default color of circle and ellipses, etc. back to be the ... (closed: fixed)">#12605</a> to this, then.
</p>
TicketjdemeyerMon, 18 Jun 2012 13:28:47 GMTattachment set
https://trac.sagemath.org/ticket/12810
https://trac.sagemath.org/ticket/12810
<ul>
<li><strong>attachment</strong>
set to <em>trac_12810-rebased.patch</em>
</li>
</ul>
<p>
Rebased to sage-5.1.beta4
</p>
TicketjdemeyerMon, 18 Jun 2012 15:52:57 GMTstatus changed; resolution, merged set
https://trac.sagemath.org/ticket/12810#comment:13
https://trac.sagemath.org/ticket/12810#comment:13
<ul>
<li><strong>status</strong>
changed from <em>positive_review</em> to <em>closed</em>
</li>
<li><strong>resolution</strong>
set to <em>fixed</em>
</li>
<li><strong>merged</strong>
set to <em>sage-5.1.beta5</em>
</li>
</ul>
Ticket