[Pulp-list] Sphinx References

[Jay Dobies]

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.

-- 
Jay Dobies
Freenode: jdob @ #pulp
http://pulpproject.org | http://blog.pulpproject.org