Guide for writing Reconcell user manuals

This manual is written in Markdown, compiled with Sphinx, and hosted on GitLab 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. 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.

How to write?

There are several nice and fast tutorials available online:

Example Section

This is a Markdown example section.

Linking a section

The next section comes next.

List test

  • Item 1
  • Item 2
    • Item 2a
  • Item 3

Image test

../_images/ReconCellLogo.pngReconcell logo

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.

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

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: