stanford-rc / www.sherlock.stanford.edu

The Sherlock website

Sherlock on the web

This repository contains the source files for the Sherlock website and documentation at https://www.sherlock.stanford.edu

The Sherlock documentation is generated from MarkDown documents hosted in this repository.

How to contribute

We're following the fork, commit, pull-request classical GitHub workflow, as described in the Forking projects GitHub guide:

1. Fork the repository on GitHub
2. Make your changes, commit and push them to your repository
3. Create a new Pull Request

Step by step instructions

There are two ways for editing documentation contents:

• editing on GitHub, which is very easy, but does not allow previewing the changes before publication,
• editing locally by cloning the repository on your local machine, which allows previewing changes, but is a bit more complicated to set up.

We recommend editing on GitHub for quick, typo-like edits, and local edition more important modifications (adding new pages, rewriting whole sections...). Both approaches follow the same fork, commit, pull-request workflow described above.

Editing on GitHub

Once you've forked the repo, Markdown pages can be edited directly within the GitHub web interface, or from the Sherlock documentation pages themselves. Each page features a pencil icon on the top-right corner.

Clicking on that icon will automatically fork the repository and bring up the GitHub editor interface. You can then modify the file with your changes. Once done, in the "Commit changes" section at the bottom of the page, add a short description for the changes, click on the green "Commit changes" button, and voilà, done.

You can also get to the page source on GitHub directly by forking the repository, going to the src/docs directory, and then editing files there.

After you've committed your changes to your forked repository, you can submit them for review by creating a Pull Request. Once your PR is accepted and merged, the website will be automatically rebuilt and deployed at https://www.sherlock.stanford.edu

Editing locally

The general idea is to fork this repository, then clone your fork on your local machine, do the modifications and preview the changes, then commit and push back to your repository on GitHub.

For more details about forking the repo, cloning it, maintaining it in sync with upstream modifications, cleaning up your changes before submitting them for review, please see this GitHub Standard Fork & Pull Request Workflow description.

1. create a fork

   Head over to the GitHub repo page and click the "Fork" button. Once you've done that, you can use your favorite git client to clone your repo or just head straight to the command line:

   $ git clone [email protected]:USERNAME/FORKED-PROJECT.git sherlock_docs/
   $ cd sherlock_docs/

2. create a branch for your modifications

   $ git checkout -b my_edits

3. install the required dependencies

   $ pip install --user -r requirements.txt

4. start the development server

   $ mkdocs serve

   This will start a development server at http://127.0.0.1:8000

5. edit the documentation files

   See the official MkDocs documentation for more details).

   All the Markdown files live in src/docs and the MkDocs configuration (structure, plugins, site settings...) are in mkdocs.yml. Updates will automatically appear at http://127.0.0.1:8000 each time a file is saved.

6. commit the changes

   When you're done with the modifications:

   $ git add .
   $ git commit -m "my commit message"

7. push the commit back to your forked repository

   $ git push origin my_edits

8. submit a pull request

   After you've committed your changes to your forked repository, you can submit them for review by creating a Pull Request. Once your PR is accepted and merged, the website will be automatically rebuilt and deployed at https://www.sherlock.stanford.edu

Sherlock cluster
Website | Documentation | Status page | Changelog

www.sherlock.stanford.edu's Issues

Update tech specs page

and keep it up-to-date automatically.

[Feedback] Getting started - /docs/getting-started/ - Windows 10 comes with an SSH client these days

https://www.sherlock.stanford.edu/docs/getting-started/#windows says:

"Microsoft Windows doesn't provide any SSH client by default. ..."

That's no longer the case - a fully functional ssh client is installed by default on MS Windows 10 since around build 1709 (October 2017).

Need docs for sh_part

https://news.sherlock.stanford.edu/posts/a-better-view-at-sherlock-s-resources

Add section on what happens after graduate

I would guess that many students finishing up would want to know to their accounts and data after they graduate, the reason being that many times work isn't done! It would be good to have an FAQ for this on the site, and possible suggestion for the PI to extend / sponsor a sunetid if needed (after it expires in a year maybe?)

[Feedback] Connection options - /docs/advanced-topics/connection/

are there any docs for how to forward vs code into sherlock?

[Feedback] Storage <small>on Sherlock</small> - /docs/storage/

It is unclear where I should store large datasets while I am actively using them to run jobs on sherlock

Add usage documentation for RClone

Based on user provided docs. I will work on this.

hello, how do i use vscode

I'm not sure if it is vscode issue or it is sherlock's issue but helpppp

[18:01:44.019] > Server did not start successfully. Full server log at /home/users/anjiecao/.vscode-server/.b3e4e68a0bc097f0ae7907b217c1119af9e03435.log >>>
[18:01:44.020] > /home/users/anjiecao/.vscode-server/bin/b3e4e68a0bc097f0ae7907b217c1119af9e03435/bin/code-server: line 12: 92714 Segmentation fault "$ROOT/node" ${INSPECT:-} "$ROOT/out/server-main.js" "$@"

<<< End of server log

maintenance period typo?

As often as possible, maintenances will take place on the first Tuesday of every month, from 8am to 12am, and will be announced 2 weeks in advance, through the usual communication channels. In case an exceptional amount of work is required, the maintenance window could be extended to 10 hours (from 8am to 6pm).

Q: Why Tuesdays 8am-12am? Why not do this late at night?

It appears this should say 8am-12pm

[Feedback] Connecting - /docs/getting-started/connecting/

Please provide instructions on how to connect to compute node on this page.

Add sbatch examples

We need a page of sbatch examples, under getting started. I'll PR this too.

Add frequently asked questions

I will do a PR for this.