[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]

[Pulp-list] Sphinx References



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


[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]