Cross-reference cheat sheet

In September-October 2015, we changed the way we add cross references that link across guides (aka RTD projects) to the documentation set. 

(Previously, if one guide included a link to another guide, we provided the URL of the destination as the link.)

Here are some notes from a team meeting on 24 Sept in case we need a cheat sheet during the transition period. 

  1. The change applies to files in the edx-documentation repo only. (We should continue to use a links.rst file and the `Name of Linked Document`_ rst markup in other repos.)
  2. For links to different RTD projects, use the :ref:`prefix:label` format for cross references.
    1. The prefix comes from the Intersphinx mappings at the bottom of the new shared file.
    2. The label is the bookmark value that we add to the top of rst files and above headings to pinpoint topic locations, using .. _Label: format.
  3. Going forward, DO NOT change any of the labels.
  4. If you do change a label, make sure to search the entire doc repo (and the analytics dashboard repo too!) and fix it everywhere.
  5. You must be connected to the Internet to ./ or  make html locally.
  6. ./ or make html looks for live, published URLs when it runs, and throws messages if it can't find them. So, make html for release notes in particular will throw warnings. 
  7. There will be one links.rst file for the entire repo, containing links to external URLs (for example, GitHub, Twitter, etc.)
  8. Again, we only have to use the  :ref:`prefix:label` format for a link to a different RTD project. For cross references within the same project, don't use the prefix – the xref will go to that location within the current guide.

List of InterSphinx Map Prefixes

Important! For the most up-to-date list, ALWAYS refer to the edx-documentation/shared/ file, and look in the "intersphinx_mapping" section at the end of the page.

Building and Running an edX Course (partner)partnercoursestaff:ref:`partnercoursestaff:Reporting Certificate Data`
 Building and Running an Open edX Course (Open edX)opencoursestaff:ref:`opencoursestaff:Text Input`
EdX Learner's Guide (partner)learners:ref:`learners:Certificates`
Open edX Learner's Guide (Open edX)openlearners:ref:`openlearners:SFD Mobile`
EdX Research Guidedata:ref:`data:pre-roll`
Using edX Insightsinsights:ref:`insights:Performance Index`
Installing, Configuring, and Running the Open edX Platforminstallation:ref:`installation:Enabling Third Party Authentication Edge`
Open edX Developer's Guideopendevelopers

:ref:`opendevelopers:Contributing to the Documentation for your Open Source Feature`

Open edX Platform APIsopenplatformapi:ref:`openplatformapi:Get the Users Enrollment Status in a Course`
Open edX XBlock API Guidexblockapi:ref:`xblockapi:EdX XBlock API Guide`
Open edX XBlock Tutorialxblocktutorial:ref:`xblocktutorial:Open edX XBlock Tutorial`