Attention

The U.S. government is closed. However, because the information this website provides is necessary to protect lives and property this site will be updated and maintained during the federal government shutdown.

For the latest forecasts and critical weather information, visit weather.gov.

To learn more, visit commerce.gov/news/blog.

Contributing via the CLI

The instructions below are focused on Linux and Mac systems, with a prerequisite that you have a recent version of Python installed on your system.

Setup authoring environment

1. Fork the documentation repository on GitHub

   Go to https://github.com/NOAA-RDHPCS/noaa-rdhpcs.github.io, and click the “Fork” button in the upper right corner.

   

2. Clone your fork of the documentation repository:

   $ git clone https://github.com/<your-github-id>/noaa-rdhpcs.github.io.git
   

3. Point your master branch to track upstream:

   $ cd noaa-rdhpcs.github.io
   $ git remote add rdhpcs https://github.com/NOAA-RDHPCS/noaa-rdhpcs.github.io.git
   $ git fetch rdhpcs
   $ git branch --set-upstream-to=rdhpcs/main
   

4. Install Sphinx and the ReadTheDocs theme locally:

   $ pip3 install -r requirements.txt
   

   This can be in your home area, a virtual environment, container, etc.

   Go to https://github.com/NOAA-RDHPCS/noaa-rdhpcs.github.io/blob/main/requirements.txt to see the list of Python packages inside requirements.txt.

5. Build the docs:

   $ make html
   

6. Locally preview the generated web pages

   Start a webserver on something like localhost:8080 that points at your noaa-rdhpcs.github.io/build/html directory. For example, using busybox:

   $ busybox httpd -p 127.0.0.1:8080 -h /home/ubuntu/noaa-rdhpcs.github.io/build/html
   

   or a python webserver (from inside the document root, i.e., build/html directory):

   $ cd build/html
   $ python3 -m http.server 8080
   ## you may add the option --bind 127.0.0.1 to bind only on the localhost address
   

   Open a browser and type localhost:8080 into the address bar to view the web pages.

Edit the docs

After having set up your environment as described above, you can reuse your local environment to make multiple changes.

1. Update your local clone from the upstream repository:

   $ git checkout main
   $ git pull
   

2. Make your edits in a new git branch:

   $ git checkout -b my-edits-branch
   ## make edits to *.rst files, using an editor like vi
   ## after my-edits-branch is created, omit the -b flag to switch to it from the master
   

3. Preview your edits

   Follow the steps in the previous section to rebuild and locally view changes

4. Add and commit your edits to your branch:

   $ git add edited_file1.rst edited_file2.rst
   $ git commit -m "message summarizing your edits"
   

5. Push your edits to your GitHub fork:

   $ git push -u origin my-edits-branch
   

6. Open a pull request on github

   After you push your branch, you should see a button to open a pull request.

   

Resources

Sphinx Quickstart

restructuredText Primer

restructuredText Reference

NOAA-RDHPCS Docs flexible style guide