#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-5.0
Component: documentation | Keywords: Sphinx
links
Work_issues: | Upstream: N/A
Reviewer: Andrey Novoseltsev, Nicolas M. Thiéry | Author: Florent
Hivert
Merged: | Dependencies: #11251,
#12490
-----------------------------------------------------+----------------------
Changes (by hivert):
* status: needs_work => needs_review
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 set up {{{intersphinx}}} so that links to Python's doc are correctly
> resolved. The patch
> [attachment:trac_9128-intersphinx_python_database-fh.patch] contains
> Python's
> crossref database downloaded from http://docs.python.org/objects.inv I'm
> also
> using intersphinx to solve links to the reference manual from the other
> documents.
>
> == Extra features ==
>
> Moreover, I add a reference target to every automatically created
> {{{.rst}}}
> file associated to python source files. It can by used to set-up a link
> toward
> the file and thus get the title rather than the module. For example
> {{{:ref:sage.categories.primer}}} setup a link to the help page with
> title
> {{{"Elements, parents, and categories in Sage: a (draft of) primer"}}}
> rather
> than
> {{{sage.categories.primer}}} which you get with the link
> {{{:mod:sage.categories.primer}}}.
>
> == Apply both: ==
>
> Note: order is irrelevant
>
> - [attachment:trac_9128-intersphinx_python_database-fh.patch]
> - [attachment:trac_9128-sphinx_links_all-fh.patch]
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 set up {{{intersphinx}}} so that links to Python's doc are correctly
resolved. The patch
[attachment:trac_9128-intersphinx_python_database-fh.patch] contains
Python's
crossref database downloaded from http://docs.python.org/objects.inv I'm
also
using intersphinx to solve links to the reference manual from the other
documents.
== New option for docbuild ==
I added the option {{{--warn-links}}} to the documentation build command
as in
{{{
sage -docbuild --warn-links reference htm
}}}
When the option is used, Sphinx will issue a warning, whenever a link is
not resolved.
== Extra features ==
Moreover, I add a reference target to every automatically created
{{{.rst}}}
file associated to python source files. It can by used to set-up a link
toward
the file and thus get the title rather than the module. For example
{{{:ref:sage.categories.primer}}} setup a link to the help page with title
{{{"Elements, parents, and categories in Sage: a (draft of) primer"}}}
rather
than
{{{sage.categories.primer}}} which you get with the link
{{{:mod:sage.categories.primer}}}.
== Apply both: ==
Note: order is irrelevant
- [attachment:trac_9128-intersphinx_python_database-fh.patch]
- [attachment:trac_9128-sphinx_links_all-fh.patch]
--
Comment:
Hi there,
I finalized the doc of this patch. I also took the chance to add a extra
option 'warn-links' which make Sphinx complains for dangling links. To
ease the review, I uploaded my changes in [attachment:trac_9128
-doc_option-fh.patch]. Those changes are folded in [attachment:trac_9128
-sphinx_links_all-fh.patch] so that you only need to apply this one and
the database patch.
--
Ticket URL: <http://trac.sagemath.org/sage_trac/ticket/9128#comment:48>
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.
