Unity Cluster User Documentation

User Documentation for Unity Cluster at UMass Amherst

Contributing

Github Guidelines

We will use branches to propose changes.

Guide for basic git commands: https://github.com/git-guides

1. Clone the repository using Github Desktop or ssh/https/git-cli.
2. Make a new branch from main while following the namescheme: <author>/<change-description>
3. Setup the local environment to run the documentation locally (described below).
4. Make the desired changes.
5. Commit and Push the changes to your branch.
6. Create a Pull Request while comparing your branch to main.
7. List tlbernardin and another team member for review.
8. Write a good description for the changes proposed no matter how small.
9. Submit Pull Request.

Local Setup

1. Install mkdocs: pip install mkdocs
2. Install the theme: pip install mkdocs-material
3. Install a plugin: pip install mkdocs-include-markdown-plugin
4. Navigate to the root of the repository and run mkdocs serve, which will start a web server you can reach from your local browser to test live edits on documentation.

Container Setup

You can also build the documentation using a containerized environment. The following steps can be accomplished via either Docker or podman.

Note If you want to build the nodelist/partitionlist tables, you will need to first download the private key and place it into the same directory as sheets-to-md/sheets-to-md.py with the name unity-sheets-key.json.

podman build -v $(pwd):/unity-docs:z -t unity-docs .
podman run --rm -v $(pwd):/unity-docs:z -p 127.0.0.1:8080:8080 unity-docs

Once the above has completed, you can view the live documentation at http://localhost:8080.

Updating the nodelist/partitionlist Tables

edit the tables here

get the private key into unity-docs/sheets-to-md/unity-sheets-key.json

Install Python modules

pip install gspread
pip install tabulate
pip install oauth2client
pip install pandas

Generate the tables

cd unity-docs/sheets-to-md
./sheets-to-md.py

Upload the new tables back to git