# Guide for writing Reconcell user manuals

This manual is written in [Markdown](http://www.writethedocs.org/guide/writing/Markdown_basics/), compiled with [Sphinx](http://www.sphinx-doc.org/en/master/index.html), and hosted on [GitLab Pages](https://about.gitlab.com/features/pages/). 

It serves as an example and a guide for writing Reconcell  __User Manuals__. 

## Just fork it
The general overview for contributing a document:
1. Fork the repository (link available soon)
2. Checkout a branch in which to apply your changes.
3. Add a markdown (.md) file and modify it with you content.
4. Add your file in the appropriate index.rst file.
5. Commit and push your changes.
6. Submit a merge request.


## The Sphinx that you don't need
Sphinx is used to compile a HTML from Markdown files. 
This is basically all you need to know about it for writing user manuals.

## It's all about the Markdown
We suggest using Markdown for writing user manuals, as it is simple to use, starightforward and can be compiled into HTML.
Of course, you can also write in reStructuredText if you wish, but for user manuals we suggest using Markdown.

### Where to write?
You can basically write in any text editor, but since a preview of the compiled text is really useful, the following options are suggested:

#### Online options

You can edit a Markdown file (.md) directly on Gitlab with a nice preview avilable.

Another site which is nice for writing .md files is [StackEdit](https://stackedit.io/). 
When you are pleased with your text you just download the file and push it on git.

#### Offline options

If you wish to write offline a number of free editors with live preview are available.
A nice free Markdown editor with a live preview can, for example, be found at [Haroopad](http://pad.haroopress.com/).

### How to write?

There are several nice and fast tutorials available online:
* [Markdownguide.org](https://www.markdownguide.org/basic-syntax)
* [Commonmark.org](http://commonmark.org/help/)
* [GitHub Cheatsheet](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet)
* etc.

## Example Section

This is a Markdown example section.

### Linking a section
The [next section](#list-test) comes next.

### List test

* Item 1
* Item 2
  * Item 2a
* Item 3

### Image test
 
![Reconcell logo](ReconCellLogo.png)

*Simple caption*

### Code Test

Inline `code` has `back-ticks around` it.

Blocks of code are fenced with three back ticks or are indented with four spaces.
```
for i=1
end
```

    for i=1
	end


### Table test
Tables are a little bit tricky in Markdown.
You can write them in raw HTML. In this way, the tables will also be generated through Sphinx.

<table border="1" bordercolor="000000" style="background-color:FFFFFF" width="400" cellpadding="3" cellspacing="0">
  <tr>
    <th>Firstname</th>
    <th>Lastname</th> 
    <th>Age</th>
  </tr>
  <tr>
    <td>Jill</td>
    <td>Smith</td>
    <td>50</td>
  </tr>
  <tr>
    <td>Eve</td>
    <td>Jackson</td>
    <td>94</td>
  </tr>
  <tr>
    <td>John</td>
    <td>Doe</td>
    <td>80</td>
  </tr>
</table>

Alternatively, you can write a table as a Markdown table. This is easier and produces a table on Git and StackEdit, but will not produce a nice table through Sphinx.

|Firstname|Lastname|Age|
|--- |--- |--- |
|Jill|Smith|50|
|Eve|Jackson|94|
|John|Doe|80|

### Comments

You can comment a code in Markdown:
<!---
The cake is a lie!
--->