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.
:ref:`prefix:label`
format for cross references... _Label:
format.make html
locally.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. :ref:`prefix:label`
format for a link to a different RTD project. For cross references within the same project, don't use the prefix.Guide | Prefix | Example |
---|---|---|
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 Guide | data | :ref:`data:pre-roll` |
Using edX Insights | insights | :ref:`insights:Performance Index` |
Installing, Configuring, and Running the Open edX Platform | installation | :ref:`installation:Enabling Third Party Authentication Edge` |
Open edX Developer's Guide | opendevelopers | :ref:`opendevelopers:Contributing to the Documentation for your Open Source Feature` |
Open edX Platform APIs | openplatformapi | :ref:`openplatformapi:Get the Users Enrollment Status in a Course` |
Open edX XBlock API Guide | xblockapi | :ref:`xblockapi:EdX XBlock API Guide` |
Open edX XBlock Tutorial | xblocktutorial | :ref:`xblocktutorial:Open edX XBlock Tutorial` |