The edx-documentation repo contains source files for most of the documentation for edX partners and the Open edX community. This repo is managed by the edX Documentation team.
API documentation that includes docstrings from code files is stored in the repository of that module.
Documentation for developers, researchers, course staff, and students is located in the language-specific subdirectories.
EdX documentation is published through Read the Docs. Links to all published documentation are available through docs.edx.org.
We welcome input from the community on any documentation issues. You can submit issues to the Documentation project in the Open edX JIRA board.
You can also email docs@edx.org.
You, the user community, can help update and revise edX documentation.
EdX documentation is created using RST files and Sphinx.
To suggest a revision, fork the project, make changes in your fork, and submit a pull request back to the original project: this is known as the GitHub Flow.
All pull requests need approval from edX. For more information, contact edX at docs@edx.org.
Before submitting a pull request, it is recommend you run the test suite on your contribution to ensure it can be compiled without errors.
To run a test compilation of a contribution, first install the prerequisites:
pip install -r shared/travis-requirements.txt
Then run the tests:
./run_tests.sh
Additionally, you can run tests for a single project:
./run_tests.sh en_us/install_operations/
A convenience script is provided to help you develop new documentation. To use it you must first install the optional tools, and then run the script.
pip install -r shared/tools.txt ./develop.sh en_us/install_operations/
It will output a line of text that looks like this:
Serving on http://127.0.0.1:9090
You can copy this URL into a web browser to see the HTML output for your project.
The command starts an HTTP server that renders the HTML for the project. This HTTP server also monitors the project and detects any changes. When you save a change to a file, the server rebuilds the HTML and refreshes your browser automatically. In this way you can rapidly see how changes you make will be rendered as HTML.