README.md

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