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:
- Fork the repository (link available soon)
- Checkout a branch in which to apply your changes.
- Add a markdown (.md) file and modify it with you content.
- Add your file in the appropriate index.rst file.
- Commit and push your changes.
- 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:
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
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: