Opened 9 years ago
Last modified 9 years ago
#12810 closed defect
Broken links in the documentation of graph/ files — at Version 9
Reported by: | ncohen | Owned by: | jason, ncohen, rlm |
---|---|---|---|
Priority: | major | Milestone: | sage-5.1 |
Component: | graph theory | Keywords: | sd40.5 |
Cc: | Merged in: | ||
Authors: | Nathann Cohen | Reviewers: | Karl-Dieter Crisman |
Report Upstream: | N/A | Work issues: | |
Branch: | Commit: | ||
Dependencies: | Stopgaps: |
Description (last modified by )
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.
Change History (10)
comment:1 Changed 9 years ago by
- Description modified (diff)
- Status changed from new to needs_review
comment:2 follow-up: ↓ 3 Changed 9 years ago by
- Status changed from needs_review to needs_work
comment:3 in reply to: ↑ 2 Changed 9 years ago by
- 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 9 years ago by
(same patch, I just added two files to the Graph documentation and removed some trailing whitespaces in a *very* stable file)
comment:5 Changed 9 years ago by
(plus some semicolumns because, of course, the files were not properly formatted :-P
)
comment:6 follow-up: ↓ 7 Changed 9 years ago by
- 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 9 years ago by
- 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 9 years ago by
comment:8 Changed 9 years ago by
- 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 9 years ago by
- Description modified (diff)
Patchbot: Apply trac_12810-rebased.patch.
I still get a bunch of warnings when I install this and rebuild the docs:
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!