Sphinx cross reference what goes in angle brackets?

Question

I see a lot of examples like

:ref:`code <target to code>`

in the Sphinx documentation, but I can't find where it defines what code and <target to code> mean. Perhaps one of them is an implicit or explicit target and the other is the path to a file??

If someone can give me examples of how to cross reference a title in a specific .rst file?

From Adding a cross-reference to a subheading or anchor in another page I know how to use the :any role, but not how to do a :ref: to a specific file.

Answer 1

From the documentation for Cross-referencing syntax:

Cross-references are generated by many semantic interpreted text roles. Basically, you only need to write

:role:`target`

and a link will be created to the item named target of the type indicated by role. The link’s text will be the same as target.

There are some additional facilities, however, that make cross-referencing roles more versatile:

• You may supply an explicit title and reference target, like in reST direct hyperlinks:

  :role:`title <target>`
  

  will refer to target, but the link text will be title.

Note that sometimes title is also called label, depending on context.