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../run_tests.sh
or make html
locally. ./run_tests.sh
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. :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.Important! For the most up-to-date list, ALWAYS refer to the edx-documentation/shared/conf.py file, and look in the "intersphinx_mapping" section at the end of the page.
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` |