Verify Documentation Using the Latest UI

To view an engineer's work in the Studio or LMS UI, ask that engineer for access to the latest sandbox, or create a sandbox based on the engineer's PR on the edx-platform repo.

Additionally, before each edx-platform release, the "stage" studio and LMS sites are refreshed so that all the changes that will be in the release are visible. This gives us an opportunity to take screen shots and otherwise sanity check before (or immediately after) a platform release goes out.

To access Stage, go to https://studio.stage.edx.org for Studio, or https://stage.edx.org for the LMS. If you don't have a Stage username and password, see edx.org, Edge, and Stage.

Test the Documentation (Terminal)

All projects must generate HTML output without warnings or errors. To make sure no errors are present, run tests on the specific guide you're working on, and then run tests on all the guides.

Build a single guide locally

This procedure will build a single guide based on the files on your local machine. It can help sanity check, but you must also test all guides using the "Test all guides" process below.

1. Optional: In Finder, go to the directory for the guide you want to build. If there is an existing build subdirectory, delete it.
2. At a command prompt, cd to the directory of the guide you want to build. For example, course_authors.
3. Enter the following command:  make html
   The command builds the project from scratch.  (If you did not remove the build subdirectory in step 1, recently introduced problems might not be detected.)
4. Review results for the project. If there are warnings or errors, address and run again.

NOTE: If the file you've changed is shared by multiple guides (files in the shared directory), you need to build and test all of the impacted guides. To locally build all guides that have directories under en_us, cd to the en_us directory and run  make html .

Test all guides

Ensure there are no build warnings or errors in any guides. 

1. At a command prompt, go to the edx-documentation directory.
2. Enter the following command: ./run_tests.sh
   The command will build all projects from scratch.  
3. Review results at the end. If there are warnings or errors, address and run again.

Test Links (doc team only)

About once every six months, run the linkchecker tool in Sphinx to make sure all the links work. 

1. At a command prompt, cd to the en_us directory.
2. Enter the following command:  make linkchecker
   The command checks all links in all projects.
3. Review results for the project. If there are warnings or errors, address and run again.

For more information, see the final comment on documentation PR 1267.