How to use intersphinx to link to sphinx or python documentation
Christoph Neuroth
I just started using sphinx 1.0 for our documentation and I'm having
trouble using the intersphinx extension. I added python and sphinx
itself in conf.py:
intersphinx_mapping = {
'python': ('http://docs.python.org/', None),
'sphinx': ('http://sphinx.pocoo.org', None)
}
And now I try to link to these documentations. But even this example
from the sphinx documentation does not work:
:ref:`comparison manual <python:comparisons>` (It will just output
"python:comparisons" in italics without a link).
Also, I don't get how I would know about these labels anyway (for
documentation I didn't write): When I have to look at the python or
sphinx documentation source to find the labels first, it's way faster
to just link the URL like `this <http://sphinx.pocoo.org/markup/
inline.html#ref-role>`_, isnt it?
Thanks for your help,
Chris
Kevin Horn
I just started using sphinx 1.0 for our documentation and I'm having
trouble using the intersphinx extension. I added python and sphinx
itself in conf.py:
intersphinx_mapping = {
'python': ('http://docs.python.org/', None),
'sphinx': ('http://sphinx.pocoo.org', None)
}
And now I try to link to these documentations. But even this example
from the sphinx documentation does not work:
:ref:`comparison manual <python:comparisons>` (It will just output
"python:comparisons" in italics without a link).
Did you also add "intersphinx" to the "extensions" value in your conf.py?
Also, I don't get how I would know about these labels anyway (for
documentation I didn't write): When I have to look at the python or
sphinx documentation source to find the labels first, it's way faster
to just link the URL like `this <http://sphinx.pocoo.org/markup/
inline.html#ref-role>`_, isnt it?
It might indeed be faster to link to the exact URL as you suggest,
but the advantage intersphinx provides that it gives you a way to
link to a specific label in the other documentation - even if it moves.
So if someone rearranges their docs, you just have to run a full rebuild
of your docs (to get the latest objects.inv files downloaded), and it should
fix any broken links you might have.
(Of course you need intersphinx to actually _work_ first ;) )
Thanks for your help,
Chris
Good luck!
Kevin Horn
DasIch
> itself in conf.py:
>
> intersphinx_mapping = {
> 'python': ('http://docs.python.org/', None),
> 'sphinx': ('http://sphinx.pocoo.org', None)
> }
the conf.py?
> And now I try to link to these documentations. But even this example
> from the sphinx documentation does not work:
> :ref:`comparison manual <python:comparisons>` (It will just output
> "python:comparisons" in italics without a link).
As expected if intersphinx is not loaded as described above.
> Also, I don't get how I would know about these labels anyway (for
> documentation I didn't write): When I have to look at the python or
> sphinx documentation source to find the labels first, it's way faster
> to just link the URL like `this <http://sphinx.pocoo.org/markup/
> inline.html#ref-role>`_, isnt it?
You won't know about the labels unless you read about the source of the
documentation of the project you are referencing.
The real advantage of intersphinx is that if you
write :py:meth`dict.pop` in your documentation with intersphinx this
will generate a link to the documentation of the dict.pop method which
should be somewhere on docs.python.org. If the location on
docs.python.org changes you only have to rebuild your documentation. A
lot of projects use Sphinx especially in the web area where this is very
helpful.
Obviously the usage of intersphinx requires will make the compiling a
bit slower but the question is how slow? I don't think it will be more
than a second if it is that much at all for most projects and it's not
necessary to build the entire documentation every time anyway, not to
mention that this is not something you do that often.
Georg Brandl
Hash: SHA1
Am 29.07.2010 01:13, schrieb DasIch:
>> I'm having trouble using the intersphinx extension. I added python and sphinx
>> itself in conf.py:
>>
>> intersphinx_mapping = {
>> 'python': ('http://docs.python.org/', None),
>> 'sphinx': ('http://sphinx.pocoo.org', None)
>> }
> Did you also add 'sphinx.extensions.intersphinx' to the `extensions` in
> the conf.py?
Correction: that should be 'sphinx.ext.intersphinx'.
>> And now I try to link to these documentations. But even this example
>> from the sphinx documentation does not work:
>> :ref:`comparison manual <python:comparisons>` (It will just output
>> "python:comparisons" in italics without a link).
> As expected if intersphinx is not loaded as described above.
>
>> Also, I don't get how I would know about these labels anyway (for
>> documentation I didn't write): When I have to look at the python or
>> sphinx documentation source to find the labels first, it's way faster
>> to just link the URL like `this <http://sphinx.pocoo.org/markup/
>> inline.html#ref-role>`_, isnt it?
> You won't know about the labels unless you read about the source of the
> documentation of the project you are referencing.
True. At first, I was also against allowing "ref" labels to be referenced,
but added it because a few users requested it.
> The real advantage of intersphinx is that if you
> write :py:meth`dict.pop` in your documentation with intersphinx this
> will generate a link to the documentation of the dict.pop method which
> should be somewhere on docs.python.org. If the location on
> docs.python.org changes you only have to rebuild your documentation. A
> lot of projects use Sphinx especially in the web area where this is very
> helpful.
Exactly. In the case of (Python) objects, you only specify the object's
canonical name, and intersphinx cares about where to link, if it is
possible.
> Obviously the usage of intersphinx requires will make the compiling a
> bit slower but the question is how slow? I don't think it will be more
> than a second if it is that much at all for most projects and it's not
> necessary to build the entire documentation every time anyway, not to
> mention that this is not something you do that often.
The inventories are cached by default, so you won't need to download them
every time you do an (incremental) build.
Georg
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.0.16 (GNU/Linux)
iEYEARECAAYFAkxR6csACgkQN9GcIYhpnLAcTgCfZRwPqwMmThLCc6D4XDpYxy4G
MagAn2i0n8czRxw6hvHWg6dyjbjJ3fCx
=yXg4
-----END PGP SIGNATURE-----
Christoph Neuroth
> (Of course you need intersphinx to actually _work_ first ;) )
so on), but the one with the :ref: from the documentation does not
work for me. And how do I link to sphinx documentation? If I want to
link e.g. to the "domains" page, would that be :sphinx:`domains`?
thanks :)
Georg Brandl
Hash: SHA1
That should be :ref:`sphinx:domains`. There have been problems with the
inventory on sphinx.pocoo.org for a few days, but it should work now.
Georg
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.0.16 (GNU/Linux)
iEYEARECAAYFAkxSjrkACgkQN9GcIYhpnLC9EgCgr8UOx/Oaj50R2NBVQJg+m54p
JcUAn1BiRAwz6cWczM3XPUN37mt0OI3E
=QaF9
-----END PGP SIGNATURE-----
Christoph Neuroth
> inventory on sphinx.pocoo.org for a few days, but it should work now.
However, I cannot do this (from the docs): "supply an explicit title
and reference target: :role:`title <target>` will refer to target, but
the link text will be title.":
I tried these two links:
:py:mod:`Foo-Test <doctest>`
:ref:`Foo Domain <sphinx:domains>`
Both have the title from the inventory (doctest / Sphinx Domains) as
the link text instead of my explicit title.
Chris
Georg Brandl
Hash: SHA1
That was another bug in Intersphinx (#480), which is now fixed in trunk
and will be released shortly.
Georg
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.0.16 (GNU/Linux)
iEYEARECAAYFAkxauw0ACgkQN9GcIYhpnLB6uwCggxQfWaFQ9vL1zqifnxGcXzr1
wtIAoJ3BYHGnQpWFGSpdqprXxnd2XlVd
=0Ka6
-----END PGP SIGNATURE-----