User Guide for the UChicago Research Computing Center's High Performance Computing Clusters

View the docs: https://rcc-uchicago.github.io/user-guide/

Make a suggestion or report an issue: https://github.com/rcc-uchicago/user-guide/issues/new

Edit the guide yourself

1. Install Material for MkDocs Run the following line in your command line interface (terminal/powershell):

   pip install mkdocs-material
   

   If already installed, update for latest functionality:

   pip install --upgrade mkdocs-material
   

2. Clone this repository to your machine.

   git clone https://github.com/rcc-uchicago/user-guide.git rcc-user-guide
   

3. Build the site locally
   Enter the repository (rcc-user-guide) and create a new branch for your edits

   cd rcc-user-guide
   git checkout -b my-edits
   

   Then run:

   mkdocs serve
   

   mkdocs will open up its built-in dev server that lets you preview documentation as you work on it. Simply open the provided address (something like: http://127.0.0.1:8000/) in your browser of choice, and you should see the user guide. As you make changes to the source documents, this site will automatically update. For more information, see here.

   If there are messages about missing modules, e.g. monorepo, install them

   pip install mkdocs-monorepo-material
   

   or

   pip install mkdocs-monorepo-plugin
   

4. Edit content
   Make whatever edits or additions to the user guide by editing the source markdown documents, located in docs/. (Editable canva infographics: RCC Workflow, Running Jobs Workflow).

5. Update mkdocs.yml
   If you add any new pages or change any page names, be sure to update the nav section in mkdocs.yml, and check the dev server to ensure the updated nav is working.

6. Submit a pull request
   When you've made your changes, commit the changes you have made in your branch, push the new branch to GitHub:

   git add [your added files, if any]
   git commit -a
   git push --set-upstream origin my-edits
   

Then open the GitHub repo website (https://github.com/rcc-uchicago/user-guide) on your browser, go to your my-edits branch and click on Create pull request or Compare and create pull request.

Remember to write a descriptive summary of the changes in the pull request (PR). On the hand-side panel, select at least one reviewer from the list. You can push more changes to the PR from your branch, if necessary, after clicking the PR is submitted.

A PR is only considered ready to merge upon at least one admin's approval. To facilitate the review process, you may want to remind the reviewer(s).

The reviewer will approve the PR, or suggest further changes that need to be made.

The submitter needs to address the suggestions and questions from the reviewers.

Once all the changes are satisfactory to the reviewer, the PR will then be merged by a writer or an admin.