Guide for writing Reconcell user manuals¶
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:
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.
This is a Markdown example section.
- Item 1
- Item 2
- Item 2a
- Item 3
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
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.
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.