Christoph Neuroth | 28 Jul 12:47 2010

How to use intersphinx to link to sphinx or python documentation

Hi,

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

--

-- 
You received this message because you are subscribed to the Google Groups "sphinx-dev" group.
To post to this group, send email to sphinx-dev <at> googlegroups.com.
To unsubscribe from this group, send email to sphinx-dev+unsubscribe <at> googlegroups.com.
For more options, visit this group at http://groups.google.com/group/sphinx-dev?hl=en.
(Continue reading)

Kevin Horn | 29 Jul 00:52 2010
Picon

Re: How to use intersphinx to link to sphinx or python documentation

On Wed, Jul 28, 2010 at 5:47 AM, Christoph Neuroth <christoph.neuroth <at> googlemail.com> wrote:
Hi,

Howdy!
 
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
 

--
You received this message because you are subscribed to the Google Groups "sphinx-dev" group.
To post to this group, send email to sphinx-dev <at> googlegroups.com.
To unsubscribe from this group, send email to sphinx-dev+unsubscribe <at> googlegroups.com.
For more options, visit this group at http://groups.google.com/group/sphinx-dev?hl=en.
Christoph Neuroth | 30 Jul 10:35 2010

Re: How to use intersphinx to link to sphinx or python documentation

> Did you also add "intersphinx" to the "extensions" value in your conf.py?
Yup :)

> (Of course you need intersphinx to actually _work_ first ;) )
Actually, it works when I use :py:mod:`unittest` (and and py:func: and
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 :)

--

-- 
You received this message because you are subscribed to the Google Groups "sphinx-dev" group.
To post to this group, send email to sphinx-dev <at> googlegroups.com.
To unsubscribe from this group, send email to sphinx-dev+unsubscribe <at> googlegroups.com.
For more options, visit this group at http://groups.google.com/group/sphinx-dev?hl=en.

Georg Brandl | 30 Jul 10:35 2010

Re: Re: How to use intersphinx to link to sphinx or python documentation


Am 30.07.2010 10:35, schrieb Christoph Neuroth:
>> Did you also add "intersphinx" to the "extensions" value in your conf.py?
> Yup :)
> 
>> (Of course you need intersphinx to actually _work_ first ;) )
> Actually, it works when I use :py:mod:`unittest` (and and py:func: and
> 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`?

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
Christoph Neuroth | 3 Aug 10:33 2010

Re: How to use intersphinx to link to sphinx or python documentation

> 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.
Thanks, that works for me 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

--

-- 
You received this message because you are subscribed to the Google Groups "sphinx-dev" group.
To post to this group, send email to sphinx-dev <at> googlegroups.com.
To unsubscribe from this group, send email to sphinx-dev+unsubscribe <at> googlegroups.com.
For more options, visit this group at http://groups.google.com/group/sphinx-dev?hl=en.

Georg Brandl | 5 Aug 15:22 2010

Re: Re: How to use intersphinx to link to sphinx or python documentation


Am 03.08.2010 10:33, schrieb Christoph Neuroth:
>> 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.
> Thanks, that works for me 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.

That was another bug in Intersphinx (#480), which is now fixed in trunk
and will be released shortly.

Georg
DasIch | 29 Jul 01:13 2010

Re: How to use intersphinx to link to sphinx or python documentation

> 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?

> 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.

--

-- 
You received this message because you are subscribed to the Google Groups "sphinx-dev" group.
To post to this group, send email to sphinx-dev <at> googlegroups.com.
To unsubscribe from this group, send email to sphinx-dev+unsubscribe <at> googlegroups.com.
For more options, visit this group at http://groups.google.com/group/sphinx-dev?hl=en.

Georg Brandl | 29 Jul 22:51 2010

Re: How to use intersphinx to link to sphinx or python documentation


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

Gmane