This section provides information about the tools used to create edX documentation, and gives guidelines for translating or updating documentation in the edx-documentation GitHub repository.
For information, see the following topics.
See ExampleRSTFile.rst for examples of most of the formatting used in edX documentation files.
For information about the tools that the edX Documentation team uses to create documentation, see this wiki page: https://openedx.atlassian.net/wiki/display/DOC/Documentation+Tools
Our documentation source files are .rst (restructuredText) files. In addition to basic information that we provide about working with our source files, you can find resources online, including the restructuredText Primer and http://docutils.sourceforge.net/rst.html#user-documentation.
Our documentation source files reside in a GitHub repository: edx-documentation. The folder structure within the repository is critical to our process and should not be modified. Each .rst file results in one page of HTML output.
For information about the folder structure, and creating folder for a new language, see Documentation Translation Process.
This section covers .rst formatting most commonly used in our source files. For examples of the formatting explained here, refer to ExampleRSTFile.rst.
Formatting in .rst files relies on vertical alignment. Exact indents are important. Text that is on the same line as an .rst tag and text that is indented to the same level on following lines are interpreted as being part of the same block.
The level of a heading is indicated by a series of characters above and below the heading text.
H1: pound symbols (#)
H2: asterisk (*)
H3: equals symbol (=)
For correct formatting, you must have the same number of the special tag characters above and below the heading text, and heading text cannot extend beyond the markers. If translated heading text is longer than the original English text, make sure to extend the markers so that they are at least the same length as translated text.
In addition to the first three levels of headings, up to three further levels can be defined, but are rarely used. These heading levels 4, 5, and 6 have a row of special characters only below the heading text. Like the top 3 heading levels, heading text cannot extend beyond the markers. If a translated heading is longer than the original, extend the markers to at least the same length as the translated heading.
H4: asterisk (*)
H5: equals symbol (=)
H6: tilde (~)
A heading level that is defined by two rows of a particular special character above and below the heading text is interpreted as being distinct from a heading level that uses that same character, but only below the heading text.
Create automatic numbered lists using the hash symbol followed by a period, for each item in the numbered list. For example,
Select Advanced Settings.
Find the Course Advertised Start Date policy key.
Enter the value you want to display.
In some cases, for example if an automatic numbered list is interrupted by multiple paragraphs or a nested list, you need to enter a number in place of the hash symbol to restart the numbered list at the correct number.
Create bulleted lists using the asterisk symbol followed by a period, for each item in the bulleted list. For example,
Who is teaching the course?
What university or college is the course affiliated with?
What topics and concepts are covered in your course?
Why should a learner enroll in your course?
For both numbered and bulleted lists, ensure that wrapped lines are indented to align with first character of text in the first line of each list item.
Nested lists are supported, but should be checked carefully in output to make sure numbering or indented levels are correct.
Tables are tagged using
Each table has the number of columns and their associated relative widths indicated in a width tag.
For proper formatting, the asterisk indicating each row must align vertically, and the hyphens indicating each column must also align. Empty cells must be accounted for, so that each column in a row is always marked, even if there is no content in the table cell. An example of an empty cell is the second column in the first row of the following example.
For additional examples of tables, see the example .rst file
In inline text, any text can be formatting as code (monospace font) by
enclosing the selection within a pair of double “grave accent” characters. For
these words are formatted in a monospace font when the
documentation is output as PDF or HTML.
For larger blocks of code that are provided as examples in documentation, use the code-block tag. Here is a code block. For examples, see ExampleRSTFile.rst.
<problem> <annotationresponse> <annotationinput> <text>PLACEHOLDER: Text of annotation</text> <comment>PLACEHOLDER: Text of question</comment> <comment_prompt>PLACEHOLDER: Type your response below:</comment_prompt> <tag_prompt>PLACEHOLDER: In your response to this question, which tag below do you choose?</tag_prompt> <options> <option choice="incorrect">PLACEHOLDER: Incorrect answer (to make this option a correct or partially correct answer, change choice="incorrect" to choice="correct" or choice="partially-correct")</option> <option choice="correct">PLACEHOLDER: Correct answer (to make this option an incorrect or partially correct answer, change choice="correct" to choice="incorrect" or choice="partially-correct")</option> <option choice="partially-correct">PLACEHOLDER: Partially correct answer (to make this option a correct or partially correct answer, change choice="partially-correct" to choice="correct" or choice="incorrect") </option> </options> </annotationinput> </annotationresponse> <solution> <p>PLACEHOLDER: Detailed explanation of solution</p> </solution> </problem>
Boldface is used for labels that are visible in the user interface. The UI text is surrounded by double asterisks. For example, bold.
Italics are rarely used. Text surrounded by single asterisks is rendered in italics.
Monospace text is used for
code examples. Text surrounded by double grave
accent characters (``) is rendered in monospace font. Within the pair of
double grave accents, further text formatting symbols is not recognized. For
more information, see Code Examples.
Make sure double quotation marks and apostrophes are straight (“) or (‘), not curly quotatation marks and apostrophes, which might be introduced when text is cut and pasted from other sources or editors.