Research Computing Public Documentation

This repository contains the source files for the Research Computing documentation.

HPC users can submit issues and bugs in the documentation here.

---

NOTE: This is the explorer-main branch

All changes to RTD for Explorer (the new cluster) will happen here.

While making any change that is intended for Explorer, please create a branch off of this branch instead of master.

After developing the change, merge the change back into this branch.

Eventually, we plan to make a final release for Discovery, and then bring this branch to master, to serve as the main documentation.

Basic Development Workflow

Following are the basic steps for contributing to the RC documentation.

1. In the terminal, go to the folder where we want to clone the repo.

2. Use the following command:

git clone https://github.com/northeastern-rc/rc-public-documentation.git0

This should result in an output similar to following:

Cloning into 'rc-public-documentation'...
remote: Enumerating objects: 9694, done.
remote: Counting objects: 100% (2891/2891), done.
remote: Compressing objects: 100% (733/733), done.
remote: Total 9694 (delta 2413), reused 2371 (delta 2158), pack-reused 6803
Receiving objects: 100% (9694/9694), 91.99 MiB | 10.76 MiB/s, done.
Resolving deltas: 100% (6479/6479), done.`

3. If we already have the documentation project on our computer, we run the following commands in the terminal.

git checkout master
git pull

This should bring the local copy of the project to the same state as the remote copy (master). We should get a message similar to the following

Already on 'master'
Your branch is up to date with 'origin/master'.

or

Already up to date.

4. Now, to do our work, we’ll create a new branch from master and switch to this new branch, using the following command:

git checkout -b new-branch-name

We can replace the new-branch-name with any appropriate name.

5. We can use the command git branch to check if we are on the branch that we just created, which we should be working on, which should result in the following, (with the * next to the name of the branch we are working on)

*new-branch-name
master

6. We can now make all the changes we want to make for the specific small task/edit we want to do.

7. Once done with the change, use the following commands to add and commit the changes, with a relevant commit message.

git add .
git commit -m “This is the commit message”`

(A commit message summarizes what the change is about. Notice the . at the end of git add, which tells to stage all the modified/new files.)

8. To preview documentation changes on our local machine, we can build and run the docker container (instructions here) and navigate to the corresponding page.

9. Now, the changes are ready to be pushed to remote. To push, use the following command:

git push

10. The above command should create a pull request (PR) on Github. Add reviewers to your PR for reviewing the changes. Once the review is complete someone can merge the PR, completing the process.

Advanced Development

Clone repo:

git clone git@github.com:northeastern-rc/rc-public-documentation.git

Then, either open PyCharm and create python environment (some find easier to create environment using PyCharm):

OR, do so via the command-line:

cd rc-public-documentation

python3.11 -m venv .venv
source venv/bin/activate
pip install --upgrade pip

---

Next, for those using Mac, install pre-commit via brew:

brew install pre-commit

For those on windows, use pip:

pip install pre-commit

Then, install pre-commit for RTD development:

$ pre-commit install
pre-commit installed at .git/hooks/pre-commit

pip install -r docs/requirements.txt

---

Install Dependencies:

Launch VS-Code and open the project folder.

Install myst-plugin-install; also, install directly from VS-Code by searching Extensions for myst.

You can use the amazing markdown lint VS Code extension developed by David Anson. Here are the steps:

• Press F1 to open the VS Code Command Palette.
• Type ext install markdownlint to find the extension
• Press Enter or click the cloud icon to install it
• Restart Visual Studio Code if prompted

Or for package development:

pip install myst-parser
npm install -g myst-cli

• Open Visual Studio Code
• Press Ctrl+P/Ctrl+P/⌘P to open the Quick Open dialog
• Type ext install markdownlint to find the extension
• Click the Install button, then the Enable button

You can also create a separate Window pane to preview your Markdown. To do this:

• Press F1 to bring up the VS Code Command Palette.
• Type “mark” to narrow down the list of commands to “markdown” commands.
• Click “Markdown: Open Preview to the Side as shown here:
• Markdown Preview

Additional

• Code Spell Checker
• Markdown helper
• emojisense
• markdown-all-in-one

https://sphinx-design.readthedocs.io/en/latest/dropdowns.html

Contributing

We welcome all contributions! See the Contributing Guide for more details.