[Pulp-list] Sphinx References

[Nick Coghlan]

On 05/15/2012 05:50 AM, Jay Dobies wrote:
> Something I'm finding more and more useful is creating references
> between page sections in sphinx. References are not namespaced and must
> be unique across the entire sphinx project (keep in mind we have one
> project for REST API docs, a different one for the user guide, etc), but
> that's not too hard to work around.
> 
> To create a reference:
> 
> .. _repo-create:
> 
> That's very specific: Two periods, a space, underscore, name using
> hyphens (not underscores), and a single colon. Any mistake in that exact
> setup and you'll be banging your head against the keyboard wondering why
> the reference doesn't resolve.
> 
> To refer to that section, regardless of what page you're in:
> 
> :ref:`repo-create`
> 
> Again, since they are globally unique you don't need to say which page
> the section is in, just the name of it.
> 
> I've started adding them for most calls in the REST API docs and each
> subsection in the user guide as well.

For those interesting in experimenting further, here's the full docs for
cross-references:

http://sphinx.pocoo.org/markup/inline.html#cross-referencing-syntax

(Note that the "ReST" domain mentioned there is the short form of
reStructuredText, *not* the web service REST)

Cheers,
Nick.

-- 
Nick Coghlan
Red Hat Hosted & Shared Services, Brisbane