[Pulp-list] Sphinx References

Nick Coghlan ncoghlan at redhat.com
Tue May 15 00:56:39 UTC 2012

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


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


Nick Coghlan
Red Hat Hosted & Shared Services, Brisbane

More information about the Pulp-list mailing list