#9128: Sphinx should be aware of all.py to find its links
------------------------------+---------------------------------------------
Reporter: hivert | Owner: hivert
Type: enhancement | Status: needs_review
Priority: major | Milestone: sage-4.4.4
Component: documentation | Keywords: Sphinx links
Author: Florent Hivert | Upstream: N/A
Reviewer: | Merged:
Work_issues: |
------------------------------+---------------------------------------------
Description changed by hivert:
Old description:
> Though sphinx is perfectly working with target in the local module he
> isn't
> able to find reference target from other modules even if they are
> exported in
> all.py. For example, if I want to link Parent from anywhere but
> parent.pyx, I
> have to write the full path (ie.
> {{{:class:`~sage.structure.parent.Parent}}}`)
> even if it is imported in my module. I find this extremely annoying
> since, in
> the task of improving the category doc, I'm setting up a lot of huge
> cross
> references such as:
> {{{
> :meth:`Algebras.ParentMethods.algebra_generators()
> <sage.categories.algebras.Algebras.ParentMethods.algebra_generators>`.
> }}}
> I would be very happy if I had to write only
> {{{
> :meth:`Algebras.ParentMethods.algebra_generators`
> }}}
> The following patch should solve this issue
>
> I also added an option {{{SAGE_DOC_WARN_DANGLING_LINKS}}} which raises
> some
> warnings if some links aren't resolved. For example:
> {{{
> WARNING: symbol
> :meth:`ModulesWithBasis.HomCategory.ElementMethods.on_basis` linked from
> sage.categories.modules_with_basis is defined in
> sage.categories.modules_with_basis but not documented
> WARNING: undefined symbol :class:`CartesianProducts.ParentMethods` in
> module sage.categories.modules_with_basis
> }}}
> Note those two warnings aren't raised because of a wrong doc but due to
> #9107.
New description:
Though sphinx is perfectly working with target in the local module he
isn't
able to find reference target from other modules even if they are exported
in
all.py. For example, if I want to link Parent from anywhere but
parent.pyx, I
have to write the full path (ie.
{{{:class:`~sage.structure.parent.Parent}}}`)
even if it is imported in my module. I find this extremely annoying since,
in
the task of improving the category doc, I'm setting up a lot of huge cross
references such as:
{{{
:meth:`Algebras.ParentMethods.algebra_generators()
<sage.categories.algebras.Algebras.ParentMethods.algebra_generators>`.
}}}
I would be very happy if I had to write only
{{{
:meth:`Algebras.ParentMethods.algebra_generators`
}}}
The following patch should solve this issue
I also added an option {{{SAGE_DOC_WARN_DANGLING_LINKS}}} which raises
some
warnings if some links aren't resolved. For example:
{{{
WARNING: symbol
:meth:`ModulesWithBasis.HomCategory.ElementMethods.on_basis` linked from
sage.categories.modules_with_basis is defined in
sage.categories.modules_with_basis but not documented
WARNING: undefined symbol :class:`CartesianProducts.ParentMethods` in
module sage.categories.modules_with_basis
}}}
Note those two warnings aren't raised because of a wrong doc but due to
#9107.
I finally set up {{{intersphinx}}} so that links to Python's doc are
correctly
resolved. The file
[http://trac.sagemath.org/sage_trac/attachment/ticket/9128/trac_9128
-intersphinx_python_database-fh.patch trac_9128
-intersphinx_python_database-fh.patch] contains
Python's crossref database downloaded from
http://docs.python.org/objects.inv
--
--
Ticket URL: <http://trac.sagemath.org/sage_trac/ticket/9128#comment:21>
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 post to this group, send email to [email protected].
To unsubscribe from this group, send email to
[email protected].
For more options, visit this group at
http://groups.google.com/group/sage-trac?hl=en.
