#20639: Sphinx sometimes doesn't resolve :meth:`.method` references correctly
-------------------------+-------------------------------------------------
Reporter: embray | Owner:
Type: defect | Status: new
Priority: minor | Milestone: sage-7.3
Component: | Keywords:
documentation | Authors:
Merged in: | Report Upstream: Not yet reported upstream;
Reviewers: | Will do shortly.
Work issues: | Branch:
Commit: | Dependencies:
Stopgaps: |
-------------------------+-------------------------------------------------
In Sphinx it's possible to reference a method (or I guess attribute) of a
class, or also a member of a module, using a shorthand notation with a
leading dot. E.g. {{{:meth:`.order`}}} which should resolve documentation
of the `order()` method of the current class being documented.
However, I found that this often fails, it seems, especially if that
method is documented in a parent class, but not directly in some subclass.
E.g. the following error can occur when building the docs:
{{{
OSError: [graphs ] /home/embray/src/sagemath/sage/local/lib/python2.7
/site-packages/sage/graphs/digraph.py:docstring of
sage.graphs.digraph.DiGraph.reverse_edge:116: WARNING: more than one
target found for cross-reference u'edge_label':
sage.graphs.generic_graph.GenericGraph.edge_label,
sage.combinat.knutson_tao_puzzles.PuzzlePiece.edge_label
}}}
It's possible this doesn't occur when building the docs in parallel, but
when building in a single process it's inevitable in a few places.
The problem in this case is that when generating a reference for
`DiGraph.edge_label` (which is referenced in the docstring for `DiGraph`
as {{{:meth:`.edge_label`}}}) it comes up with multiple matches:
{{{
[(u'sage.combinat.knutson_tao_puzzles.PuzzlePiece.edge_label',
(u'sage/combinat/knutson_tao_puzzles', u'method')),
(u'sage.graphs.generic_graph.GenericGraph.edge_label',
(u'sage/graphs/generic_graph', u'method'))]
}}}
In this case it should of course use `GenericGraph.edge_label`, but it
doesn't recognize that `GenericGraph` is a subclass of `DiGraph` and
should be preferred. Instead this ends up generating an incorrect
reference. A workaround would be to use a more explicit reference.
I'm also not sure why it results in an `OSError` and craashes the build
instead of just producing a warning--is the doc build configured to
promote all warnings to exceptions?
--
Ticket URL: <http://trac.sagemath.org/ticket/20639>
Sage <http://www.sagemath.org>
Sage: Creating a Viable Open Source Alternative to Magma, Maple, Mathematica,
and MATLAB
--
You received this message because you are subscribed to the Google Groups
"sage-trac" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to [email protected].
To post to this group, send email to [email protected].
Visit this group at https://groups.google.com/group/sage-trac.
For more options, visit https://groups.google.com/d/optout.
