CMS Open Data Guide

MkDocs documentation for the CMS Open Data Guide.

• The Guide's philosophy
• How to contribute
  • If you are a collaborator already
  • If you are not a collborator yet
• Test locally
• Deploy

The Guide's philosophy

The main purpose of the CMS Open Data Guide is to facilitate the understanding of the CMS open data, its tools, and their usage for research.

The Guide is meant to organize pieces of information already available in the CMS CERN Open Portal site, the public CMS Twiki, the CMSSW components, etc., in a logical way, following mainly the structure of a real physics analysis project.

Therefore, the sections at the heart of this Guide should also point to practical lessons or exercises that are implemented in the sister cms-opendata-workshop organization.

How to contribute

Everyone is welcome to help build and/or improve this guide. If you find a bug or want to make a suggestion, please fill out an issue. If you would like to contribute, there are two options depending on whether you are already a collaborator of the project or not.

If you are a collaborator already

1. If you found a topic of your interest but there is no associated issue yet in the "To do" board of an open project, please comment on the corresponding checklist and tag one of the coordinators of the project. The coordinator will then interact with you to create an appropiate issue in the "To do" list so you can follow the rest of the steps below.
2. If there is already an open issue, within the "To do" board of an open project, that you are interested in working on, you can assign it to yourself and move it to the "In progress" board. Remember that you could also move an open issue to the "Discussion" or the "Need info" boards.
3. Check whether the topic, corresponding to the issue, has already a page in the file that steers the structure of the guide.
4. If there is no such a page, contact one of the coordinators of the project to create it for you or to agree to create it yourself. You could just make a comment in your issue, tagging a coordinator therein, which will trigger the discussion.
5. Once the appropiate page exists, you can start writing the relevant information either directly into the repository on the webpage or (preferably) on your own, local github area.
   • If working locally, feel free to test it first following the local testing instructions below.
   • Make sure to check for missing new lines at EOF and trailing white spaces. A simple way to check is by using the git diff and/or git diff --check commands.
   • When ready, push to to the master branch to trigger the automatic deployment.
   • Please close the issue when done.
6. The page you are creating should, in most cases, be accompanied by a workshop tutorial lesson or exercise. Ideally, the issue the page is addressing should point (if necessary) to the corresponding issue in the cms-opendata-workshop organization.

If you are not a collaborator yet

Make a direct pull request or (preferably) contact us first.

Test locally

$ mkvirtualenv cms-opendata-guide
$ pip install -r requirements.txt
$ mkdocs serve
$ firefox http://127.0.0.1:8000

Deploy

Documentation site is deployed on OpenShift.

Once a new commit is pushed to master, OpenShift will automatically trigger a new build with the latest changes.