Broken links in the documentation of graph/ files

[ncohen]

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 :-)

This patch fixes those links in the Graph database (those that *could* be fixed, actually), like #12767 already does for sage/rings/number_field.

[1] ​http://groups.google.com/forum/?fromgroups#!topic/sage-devel/c5cdBO3hvKM

Nathann

---

Apply trac_12810-rebased.patch​.

[davidloeffler]

I still get a bunch of warnings when I install this and rebuild the docs:

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

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!

[ncohen]

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!

Oh My, but you are totally right ! :-)

This was a stupid alignment problem. Patch updated :-)

Nathann

[ncohen]

(same patch, I just added two files to the Graph documentation and removed some trailing whitespaces in a *very* stable file)

[ncohen]

(plus some semicolumns because, of course, the files were not properly formatted :-P)

[kcrisman]

There remain

/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

Couldn't one just change the syntax to say

``sage.graphs.graph_latex.GraphLatex.__graphlatex_options``

instead of the following?

:data:`sage.graphs.graph_latex.GraphLatex.__graphlatex_options`

Something similar might be able to be said about

:meth:`sage.graphs.generic_graph.GenericGraph._latex_`

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.

Also, we are trying to discourage double-underscore attributes. Such as __graphlatex_options. Could this be made single-underscore (perhaps in another ticket, if appropriate)?

More comments:

• The doc looks wrong in the (short) tree.pyx - you'll see what I mean.
• The AUTHORS in matchpoly is indented too much.
• graph_plot.html can have trac #10124 written as :trac:`#10124`, I think.

All that said, it seems like it's pretty good overall.

[ncohen]

Hellooooooooooooooooo !!!

Couldn't one just change the syntax to say

``sage.graphs.graph_latex.GraphLatex.__graphlatex_options``

Done !!

Also, we are trying to discourage double-underscore attributes. Such as __graphlatex_options. Could this be made single-underscore (perhaps in another ticket, if appropriate)?

Hmmm.. I prefer to let the combinat guys deal with that, it may break code on their side.

• The doc looks wrong in the (short) tree.pyx - you'll see what I mean.

Oh, yeah. Columns.

• The AUTHORS in matchpoly is indented too much.

Done, done.

• graph_plot.html can have trac #10124 written as :trac:`#10124`, I think.

That too.

Patch updated ! Thank you for the review :-)

Nathann

[kcrisman]

Great. I'm uploading one rebased to Sage 5.1.beta1. I did get one weird error

<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

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.

[kcrisman]

Patchbot: Apply trac_12810-rebased.patch​.