Conditionals:
See:
- conditionalized paragraph in: https://github.com/edx/edx-documentation/blame/DOCS/SaudiProjects/en_us/shared/building_and_running_chapters/developing_course/course_outline.rst#L132
- Output for Partner doc (doesn't include that paragraph): http://saudi-test-edx-building-guide.readthedocs.org/en/latest/developing_course/course_outline.html#add-content-in-the-course-outline
- Output for Open edX doc (does include that paragraph): http://saudi-test-open-edx-building-guide.readthedocs.org/en/latest/developing_course/course_outline.html#add-content-in-the-course-outline
re: conditional text. I agree we should work to design our docs so that we can use this tool sparingly. When we do use, it, though, I think that we should include a comment indicating at a minimum what the related feature is by referencing the PR or JIRA story.
.. the following note is for prerequisite exams, which are currently released in open edx only and not on edx.org. when they are available on edx.org, this note should no longer be conditionalized.
Conditional text is text that appears in one guide but not the other. For example, the text might appear in the partner guide but not the Open edX guide, and vice versa.
How to Conditionalize Text
To include conditional text in partner or course author documentation, use the only directive.
Single Paragraph
To conditionalize a single paragraph, use either the .. the only:: Partners or the .. or the only:: Open_edX directive directive, and indent the paragraph under the directive. You can add the conditional text as regular text or as a note.
.. only:: Partners
Data about course enrollment is available from edX Insights. You can access
Insights from the Instructor Dashboard for your live course: after you select
**Instructor**, follow the link in the banner at the top of each page. For
more information, see `Using edX Insights`_.
.. only:: Open_edX
.. note::
If you want to require an entrance exam for your course, you also create
the exam in the course outline. Before you can create an exam, you must
set your course to require an entrance exam in Studio. For more
information, see :ref:`Require an Entrance Exam`.
Multiple Paragraphs
To conditionalize more than a paragraph, use use either the the .. only:: Partners or the or the .. only:: Open_edX directive directive, and then use an .. an include:: directive directive indented under the the only directive directive.
.. only:: Open_edX
.. include:: ../../../shared/building_and_running_chapters/running_course/Section_course_student.rst
Notes
- Conditionalized text must include a comment indicating at a minimum what the related feature is by referencing the PR or JIRA story.
.. the following note is for prerequisite exams, which are currently released in open edx only and not on edx.org. when they are available on edx.org, this note should no longer be conditionalized.
- Text inside tables cannot be conditionalized.
- Conditional text is still processed even if it isn't shown; that means you get build warnings for excluded text that has a link that's not actually shown. For example, in building partner doc, you get a warning that about the link to prereq exams in the excluded paragraphs generates a warning even though it isn't shown.
Examples
Example 1
.. Feature availability on the instructor dash applies to open edX installations only.
.. DOC-2218 A. Hodges 24 Aug 2015
...
Data about course enrollment is available from edX Insights. You can access
Insights from the Instructor Dashboard for your live course: after you select
**Instructor**, follow the link in the banner at the top of each page. For
more information, see `Using edX Insights`_.
Example 2
In the edx-documentation/en_us/shared/building_and_running_chapters/developing_course/course_outline.rst file, the "Add Content in the Course Outline" section contains the following conditionalized paragraph.
...
Note
If you want to require an entrance exam for your course, you also create the exam in the course outline. Before you can create an exam, you must set your course to require an entrance exam in Studio. For more information, see Require an Entrance Exam.
The live Open edX documentation includes this paragraph.
The live partner documentation does not include this paragraph.
More Information
The following lines show this setting in the config files for partner course author documentation and Open edX course author documentation.
...