/cms-opendata-guide

CMS Open Data Guide

Primary LanguageShell

CMS Open Data Guide

MkDocs documentation for the CMS Open Data Guide.

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.

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.
    • Please follow the content guidelines below.
    • 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.
    • Please test locally for style issues by running the command ./run-tests.sh --check-docstyle (Note that you might need to install awesome_bot)
    • When ready, push 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.

Content guidelines

Please follow these simple guidelines:

  • 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.
  • Check out the basics for markdown.
  • Do not paste big code snippets into the Guide pages.
  • If there is need to point to extended lines of code it is best to direct the user to the practical lessons or exercises that are implemented in the sister cms-opendata-workshop organization using web links.
  • The Guide is not supposed to be a copy of these tutorials (workshop) pages but rather an aid to navigate them.
  • If differentiation between Run 1 and Run 2 information is required, please use material mkdocs tabs for grouping content.
  • If you need an example of how the content is written, check out one of the already-written pages in the docs folder of this repository; this one, for instance.

Test locally

Make sure you have installed the virtualenv and virtualenvwrapper packages. Be sure to source the included virtualenvwrapper.sh script, or add it to your path in your .bashrc. For example, if virtualenvwrapper.sh was installed in /usr/local/bin, then you could type

$ source /usr/local/bin/virtualenvwrapper.sh

You may need to set the variable VIRTUALENVWRAPPER_PYTHON to your python path (verify it with which python or which python3) with:

$ export VIRTUALENVWRAPPER_PYTHON='/usr/bin/python3'

Once you have the virtualenvwrapper installed, you can list your virtual environments by typing workon

If this is your first virtual environment, when you type workon, the output will be empty. But, after installing one (as you will below), you will be able to choose it from the list. For example if you create a virtual environment called cms-opendata-guide, you can work in that environment by typing

$ workon cms-opendata-guide

You can create a virtual environment called cms-data-guide, install dependencies via pip, start up a mkdocs server, and then open a local browser by:

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

You can exit from the virtual environment with deactivate.

You can run local tests executing ./run-tests.sh. Testing requires a ruby installation. You will also need to install the ruby gem awesome_bot by issuing gem install awesome_bot and make sure that gem in accessible on your path. In addition, npx is also required by the test script. For this one should install nodejs and npm, and install it using the node package manager (npm) as npm i npx.

Note on markdown

Markdownlint is used to check your markdown. However, it does not allow inline HTML. To temporarily allow it, you can wrap your inline HTML as follows:

<!-- markdownlint-disable -->
write your inline HTML code here
<!-- markdownlint-restore -->

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.