# SCRAM documentation

[This folder](https://github.com/cms-sw/SCRAM/tree/master/docs) contains source code for SCRAM documentation hosted [Read The docs](http://scram.readthedocs.io).

## Why Read The docs

After trying multiple documentation software, we chose RTD because:

  • We are able to write content in Markdown and reStructuredText syntax;

  • It has strong search functionality;

  • Ability to version documentation, create PDF files, etc. ;

  • Ability to use hosting service for free;

  • Benefits of static page generator;

  • Possibility for themes;

  • Ability to keep documentation with source code.

## Setup

This setup is using Sphinx as a backend to generate pages which, by default, process .rst documents. We are also using recommonmark extension to digest .md documents. This setup allows document in any file format we wish while keeping benefits of using Sphinx generator.

## Editing documentation

  • conf.py - this is config path for changing styles, paths, etc. ;

  • index.rst - basically Table of content/main page. After creating new document do not forget to include its path here.

Just edit documents following Markdown or reStructuredText syntax. If creating new document or you want to change order in TOC, do not forget to edit index.rst file.

## Local development

To develop documentation locally:

```bash # in the /docs path python -m virtualenv /tmp/_env/rtd source /tmp/_env/rtd/bin/activate pip install -r requirements.txt make html

# to generate MAN page # in conf.py edit man_pages variable for required result make man nroff _build/man/scram.1 > man.txt

deactivate # deactivates virtual enviroment ```

## Format MAN pages to Markdown

In case you need convert existing MAN pages (.roff extension), check [this project](https://github.com/mle86/man-to-md). It is not perfect, so look at the workaround in [this issue](https://github.com/mle86/man-to-md/issues/1).

Example command:

`bash ./man-to-md.pl ../SCRAM/docs/man/scram.1.in > ../SCRAM/docs/man/scram-man.md `

## More info