summaryrefslogtreecommitdiffhomepage
diff options
context:
space:
mode:
authorMartin Damien <martin-damien@users.noreply.github.com>2016-06-26 15:34:16 +0200
committerven <vendethiel@hotmail.fr>2016-06-26 15:34:16 +0200
commitbe12f2009759514fdcf6bfc70cc62f4cc60c651b (patch)
tree508f2bc6cb746b4e0a964f4eaf3597bfbad0cb4b
parent095d2e2405ced6a6e42b5f270d44a6ec6e9e3cb4 (diff)
[en/RST] Add RST introduction (#1723)
* [en/RST] Add RST introduction * Fix @ in username
-rw-r--r--rst.html.markdown107
1 files changed, 107 insertions, 0 deletions
diff --git a/rst.html.markdown b/rst.html.markdown
new file mode 100644
index 00000000..161a0610
--- /dev/null
+++ b/rst.html.markdown
@@ -0,0 +1,107 @@
+---
+language: restructured text
+contributors:
+ - ["DamienVGN", "https://github.com/martin-damien"]
+filename: restructuredtext.rst
+---
+
+RST is file format formely created by Python community to write documentation (and so, is part of Docutils).
+
+RST files are simple text files with lightweight syntaxe (comparing to HTML).
+
+
+## Installation
+
+To use Restructured Text, you will have to install [Python](http://www.python.org) and the `docutils` package.
+
+`docutils` can be installed using the commandline:
+
+```bash
+$ easy_install docutils
+```
+
+If your system have `pip`, you can use it too:
+
+```bash
+$ pip install docutils
+```
+
+
+## File syntaxe
+
+A simple example of the file syntax:
+
+```rst
+.. Line with two dotes are special commands. But if no command can be found, the line is considered as a comment
+
+=========================================================
+Main titles are written using equals signs over and under
+=========================================================
+
+Note that theire must be as many equals signs as title characters.
+
+Title are underlined with equals signs too
+==========================================
+
+Subtitles with dashes
+---------------------
+
+And sub-subtitles with tilde
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can put text in *italic* or in **bold**, you can "mark" text as code with double backquote ``: ``print()``.
+
+Lists are as simple as markdown:
+
+- First item
+- Second item
+ - Sub item
+
+or
+
+* First item
+* Second item
+ * Sub item
+
+Tables are really easy to write:
+
+=========== ========
+Country Capital
+=========== ========
+France Paris
+Japan Tokyo
+=========== ========
+
+More complexe tabless can be done easily (merged columns and/or rows) but I suggest you to read the complete doc for this :)
+
+Their is multiple ways to make links:
+
+- By adding an underscore after a word : Github_ and by adding the target after the text (this have the advantage to not insert un-necessary URL inside the readed text).
+- By typing a full comprehensible URL : https://github.com/ (will be automatically converted in link)
+- By making a more "markdown" link: `Github <https://github.com/>`_ .
+
+.. _Github https://github.com/
+
+```
+
+
+## How to use it
+
+RST comes with docutils in which you have `rst2html` for exemple:
+
+```bash
+$ rst2html myfile.rst output.html
+```
+
+*Note : On some systems the command could be rst2html.py*
+
+But their is more complexe applications that uses RST file format:
+
+- [Pelican](http://blog.getpelican.com/), a static site generator
+- [Sphinx](http://sphinx-doc.org/), a documentation generator
+- and many others
+
+
+## Readings
+
+- [Official quick reference](http://docutils.sourceforge.net/docs/user/rst/quickref.html)