Publish Documentation on Read the Docs

Owned by David Baumgold (Deactivated)
Last updated: Jan 04, 2023 by Feanil Patel

When new material is ready for publication, the doc team uses Read the Docs to produce HTML output. External documentation typically is republished concurrently with every software release, and can also be updated between releases. Internal draft documentation can also be published at any time (useful for longer guides, and for guides that include images or tables.)

On Readthedocs, guides, release notes, and other deliverables are organized into "projects". You are either rebuilding an existing project or creating a new project and building that. 

Rebuilding a set of projects

We have a script to rebuild the set of most-frequently-built guides in RTD.

To run the script, cd to the ex-documentation/utilities directory on the command line and invoke ./build-rtd-documents.sh

For the list of guides that the script builds, see the script!

Rebuilding a specific existing project

  1. On the https://readthedocs.org/dashboard/ page, sign in with a username of edx. See a member of the doc team if you do not have the password for this username.

  2. Find the project you want to rebuild in the list. Projects that are published on docs.edx.org are listed in the table.  NOTE: this table is not up-to-date.


    Listed on docs.edx.org asReadthedocs Project
    EdX Partners > edX Release NotesedX Release Notes
    EdX Partners > Building and Running an edX Courseedx-Partner-Course-Staff
    EdX Partners > Using edX InsightsedX Insights
    EdX Partners > edX Research Guidedevdata
    EdX Partners > EdX Learner's GuideedX Guide for Students
    Open edX doc: <Named Release> Open edX Release NotesOpen edX Release Notes
    Open edX doc  Latest/Named Version > Installing, Configuring, and Running the Open edX PlatformedX Installing, Configuring, and Running
    Open edX doc: Latest/Named Version > Building and Running an Open edX CourseOpen edX Building and Running a Course
    Open edX doc: Latest/Named Version > Open edX Learner's GuideOpen edX Learner Guide
    Open edX doc: Latest Version > Open edX Developer's GuideedX Developer Guide
    Open edX doc: Latest Version > edX Open Learning XML Guide - Alpha VersionedX Open Learning XML
    Open edX XBlock > Open edX XBlock API GuideXBlock
    Open edX XBlock > Open edX XBlock TutorialXBlock Tutorial
    Open edX REST APIs > Open edX Platform APIsedX Platform API
    Open edX REST APIs > Open edX Data Analytics API Version 0 - Alpha VersionedX Data Analytics API

  3. Click the row for the project you want to rebuild. 

  4. On the page that opens, locate Build a version.
  5. Select the build version ("latest" except for named Open edX releases), and then click Build version.
    The Recent Builds page opens, and Read the Docs begins building the output for the project. Build states that occur during the process are as follows:
    1. Triggered version latest (html): you have manually triggered the build process on a guide.
    2. Cloning version latest (html): Read the Docs is cloning your content in preparation for building the guide.
    3. Building version latest (html): Read the Docs is in the process of building your guide.
    4. Passed version latest (html): Read the Docs has finished building your guide. 
    5. Failed version latest (html): The build failed to publish. Note that if you verify and test your guide locally and work through any issues, the build should not fail.
  6. The amount of time this takes to build a guide varies based on the time of day (load on RTD) and the length of the guide.
  7. Refresh your browser occasionally to see if the build passed or failed. When the top line in the table says Passed version <version name> (html), the version of the guide available on docs.edx.org has automatically been updated. 
  8. To ensure that your changes appear in the docs, select View Docs in the upper right corner of the Recent Builds page and navigate to your changes to view them live.

Creating a new project

  1. Open the https://readthedocs.org/dashboard/ web page. See a member of the doc team if you do not have the edX login information.
  2. Right-click on one of the existing projects (example: edx-partner-course-staff) and open it in a new window.
  3. In the browser window for the edx-partner-course-staff project, click Admin then Advanced Settings. You can use the info on this page as a reference.
  4. Back on the initial RTD dashboard, click Import a Project.
  5. Supply a name for the project (for example, "DRAFT - {name}")
  6. Supply the repository name (typically, https://github.com/edx/edx-documentation).
  7. Select Edit advanced project options, then click Next.
  8. Enter a description for the project, then click Finish.
  9. Back on the page for your new project, click Admin then click Advanced Settings. Use the existing project as a reference as you fill out the location of the Python configuration file, the Default branch, and the Privacy level ("Private" for a draft!).  For the edx-documentation repo they should be:
    1. Default branch: master
    2. Requirements file: requirements/base.txt
    3. Python interpreter: 3.x
    4. Install project: leave this unchecked
    5. Python configuration file: the path to your conf.py, for example: en_us/open_edx_course_authors/source/conf.py

  10. Click Submit. You can now build your new RTD project as described above.

Add a subproject to edX Projects

New guides must be a subproject in edX Projects for intersphinx linking to work. Draft projects should not be added to edX Projects, but any new permanent guide should be added.

  1. Open the https://readthedocs.org/dashboard/ web page.
  2. Click the project that you want to add as a subproject to edX Projects.
  3. On the project page, under Short URLs, copy either of the 2 Short URLs that are provided, and remove the domain. For example, for "edx-guide-for-students.readthedocs.org", remove "readthedocs.org". For "edx-guide-for-students.rtfd.org", remove "rtfd.org". Keep the truncated short URL (e.g. "edx-guide-for-students") in your clipboard for pasting.
  4. Go back to the https://readthedocs.org/dashboard/ web page and click the edX project.
  5. Click Admin then Subprojects.
  6. At the bottom of the list of existing subprojects, paste the truncated short URL for the subproject into the Subproject field.
  7. Leave the Alias field empty. 

  8. Click Submit. Your project is added as a subproject to edX.

Creating Draft HTML Documents for Reviewers

To make sure our documents are complete and accurate, we occasionally need to create private HTML versions for non-GitHub users to review. To do this, you use readthedocs.org.

  1. Save your work on your github branch.
  2. Go to http://readthedocs.org and sign in with the edX account (see Mark for credentials if necessary).
  3. In the upper-right corner of the page, click Dashboard, or go to https://readthedocs.org/dashboard.
  4. Open a separate browser window to the Dashboard page, then select one of the existing Draft projects and navigate to Admin > Advanced Settings.
  5. In the original browser window, create a new project:
    1. Click Import a Project, and then Import Manually.
    2. Enter a name that begins with DRAFT and that ends with the current date. For example, DRAFT: LTI for Course Teams 20150831
    3. For the Repository URL, enter http://github.com/edx/edx-documentation.git

    4. Leave the other fields as-is, and click Next.

  6. At the top left of the page, click Admin and then click Advanced Settings. You can refer to the existing draft project in the other browser window while you fill these fields out.

    1. in the Requirements file field, enter the location of the requirements file, which is probably shared/travis_requirements.txt.
    2. In the Python configuration file field, enter the location of the conf.py file for the document you want to build, beginning from the en_us directory. For example, enter 
      en_us/course_authors/source/conf.py. (This path will be nearly identical for all projects; the only difference is the folder between en-us and source. In this example, the folder is course_authors.)
    3. In the Default branch field, enter the name of your current branch. For example, your current branch may be sylvia/BLD-614.
    4. Clear the check boxes for other types of output.
    5. Under Privacy Level, select Private.
    6. At the bottom of the page, click Save.
  7. On the page that opens, locate Versions, and make sure that Latest is selected. Then select Build. 
  8. When the document has finished building, send its URL to the reviewers or add it to the PR (see the Doc Team Pull Request Template).
  9. Rebuild the project as needed while you address review comments.
  10. When all questions have been answered, delete the project. Click the name of your project, select Admin, and then click delete at the bottom of the page.