GitHub repository: https://github.com/JCSDA-internal/jedi-docs and https://github.com/JCSDA/jedi-docs

Dashboard: https://readthedocs.com/dashboard/

Read the Docs Documentation: https://docs.readthedocs.io/en/stable/

JEDI Documentation: https://jointcenterforsatellitedataassimilation-jedi-docs.readthedocs-hosted.com/en/latest/

Table of Contents

About

Read the Docs is used to generated our main JEDI documentation. Our public repository mirrors the JCSDA-Internal repository. This page will be updated with the Infrastructure's teams procedures and maintenance. We use readthedoc.com and not .org, .org is the public version. Read the Docs has webhooks set up via GitHub that will trigger a doc build when merging a PR or with a commit. You can see the Read the Docs line in the jedi-docs PR with an updated rendering reflecting the changes in the PR. An example rendering from a PR is #741. There area a couple of necessary files for Read the Docs inside our jedi-docs repository. docs/requirements.txt is needed to render the documentation and docs/conf.py is the main configuration file used when building. Read the Docs will email the Owner (currently Steve H.) if Read the Docs is updated and changes are needed to required files. 

Procedures

Adding a new user or administrator

  1. Log into https://readthedocs.com/dashboard/ and send a user request to join the "jointcenterforsatellitedataassimilation” team. You can follow this URL to the correct page to send a user request email.
  2. The new user will receive an email. They should follow the link and set up an account. It is best to use your UCAR email.
  3. If you need to add the new user as an Owner, navigate to https://readthedocs.com/organizations/jointcenterforsatellitedataassimilation/owners/ and add their email address or username used to the "Add Owner" section.

Updating the credit card

Occasionally our JCSDA administrator might need to update the card that pays for Read the Docs. In the past an Owner will give them access to their account in order the change the credit card information. Typically this is done with a UCAR P-card. To manage the subscription and update the credit card, navigate to https://readthedocs.com/organizations/jointcenterforsatellitedataassimilation/subscription/. 

Adding a tag for new Skylab releases

With each Skylab release, a new tag is issued for our JEDI Documentation hosted on Read the Docs. The following steps are taken to set up a new release tag. You should already have a release tag created in GitHub before following these steps.

  1. Log into Read the Docs and navigate to the jedi-docs project page. 
  2. Click on "versions" in the top menu bar. If you have difficulty finding this option try this url. 
  3. Scroll down to "Activate a version" and type in the new release tag (ie 9.0.0). 

Configuring ReadTheDocs and GitHub for proper rendering of the documentation in our private jedi-docs repo

When a PR is submitted or updated in the jedi-docs repo, ReadTheDocs will render the documentation and a link to that rendering is provided in the PR check on GitHub.

Clicking on the "Details" button in the checks list takes the user to the newly rendered documentation. This is a great feature for the submitter and reviewers of the PR. However, to configure this with a private repo (i.e., our JCSDA-internal/jedi-docs repo) requires a workaround to help mitigate security risks.

Here are instructions on how to configure this capability.

  • readthedocs.com uses git@github.com/path/to/repo for private repositories, and a deploy key in the repo that is the public SSH key exported by readthedocs.com
  • git-lfs "doesn't do" authentication via ssh, only https so they way to configure this is - to avoid any security risks:
    1. Create a new Github user jedi-docs-reader
    2. Create a Github token for the reader
    3. Give this user read-only access to jcsda-internal/jedi-docs only - NOTHING else
    4. Reconfigure the readthedocs build project to use https://jedi-docs-reader:XXXXXX@github.com/JCSDA-internal/jedi-docs.git
      1. Replace the "XXXXXX" in the URL above with the GitHub token that was generated in step "b" above.
  • The github token of this jedi-docs-reader will be in the build logs, therefore the need for a separate user with minimal permissions.
  • No labels