Opened 7 years ago

Closed 7 years ago

#12810 closed defect (fixed)

Broken links in the documentation of graph/ files

Reported by: ncohen Owned by: jason, ncohen, rlm
Priority: major Milestone: sage-5.1
Component: graph theory Keywords: sd40.5
Cc: Merged in: sage-5.1.beta5
Authors: Nathann Cohen Reviewers: Karl-Dieter Crisman
Report Upstream: N/A Work issues:
Branch: Commit:
Dependencies: Stopgaps:

Description (last modified by kcrisman)

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.

Attachments (2)

trac_12810.patch (44.9 KB) - added by ncohen 7 years ago.
trac_12810-rebased.patch (45.1 KB) - added by jdemeyer 7 years ago.
Rebased to sage-5.1.beta4

Download all attachments as: .zip

Change History (15)

comment:1 Changed 7 years ago by ncohen

  • Description modified (diff)
  • Status changed from new to needs_review

comment:2 follow-up: Changed 7 years ago by davidloeffler

  • Status changed from needs_review to needs_work

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!

comment:3 in reply to: ↑ 2 Changed 7 years ago by ncohen

  • Status changed from needs_work to needs_review

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

comment:4 Changed 7 years ago by ncohen

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

comment:5 Changed 7 years ago by ncohen

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

comment:6 follow-up: Changed 7 years ago by kcrisman

  • Keywords sd40.5 added
  • Reviewers set to Karl-Dieter Crisman
  • Status changed from needs_review to needs_work

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.

comment:7 in reply to: ↑ 6 Changed 7 years ago by ncohen

  • Status changed from needs_work to needs_review

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

Changed 7 years ago by ncohen

comment:8 Changed 7 years ago by kcrisman

  • Status changed from needs_review to positive_review

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.

comment:9 Changed 7 years ago by kcrisman

  • Description modified (diff)

Patchbot: Apply trac_12810-rebased.patch.

comment:10 Changed 7 years ago by ncohen

Ohhh thank you !!

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.

Nathann

comment:11 Changed 7 years ago by jdemeyer

  • Status changed from positive_review to needs_work

This patch conflicts with #12605.

comment:12 Changed 7 years ago by kcrisman

  • Status changed from needs_work to positive_review

Since I'm the one that generated the latest rebased patch as well as #12605, I declare by fiat that this is the one that will be have priority. I'll rebase #12605 to this, then.

Changed 7 years ago by jdemeyer

Rebased to sage-5.1.beta4

comment:13 Changed 7 years ago by jdemeyer

  • Merged in set to sage-5.1.beta5
  • Resolution set to fixed
  • Status changed from positive_review to closed
Note: See TracTickets for help on using tickets.