Use reStructuredText over Markdown for documentation

[yukiisbored]

Continuation from #972 (comment).

The reason for this is because:

1. Obvious native support with sphinx
2. Not as primitive as Markdown (directives, roles, etc)
3. You're likely generate more issues with Markdown than reStructuredText (e.g Headings)
4. Extensible

I'm open for everyone to put their opinions in this issue so we can discuss if this is a good idea or not. I personally do not like Markdown as much as asciidoc or reStructuredText because it's pretty unpredictable and I usually doubt a lot wheter it'll parse correctly or have horrible issues (or even worse, unnoticeable issues).

[mariobehling]

Well, this would divert from other FOSSASIA projects. It would also not be formatted correctly in GitHub itself as far as I understand. This is really nice if devs want to just go through things here. The Open Event Orga Server now uses Jekyll and generates the site from md files in the project: https://github.com/fossasia/open-event-orga-server/tree/gh-pages Compare: http://dev.eventyay.com

[sudheesh001]

I would like to be more in favour of jekyll than read the docs. The codebase so far has primarily been java, and readthedocs involves python to be integrated through something that I am not against but something I am sure isn't really needed. Do we really need 2 programming languages and builds to get this repo up and running for a contributor ? Not really. I think we should stick to jekyll and not to read the docs.

@Orbiter @daminisatya @shivenmian What's your opinion on this ?

[niccokunzmann]

@yukiisbored according to #1003 markdown is favored. We can use a markdown2rst converter. This would require reading through the changes if anything is out of sync between the two files.
What do you think?

#1063 (related for me)

[yukiisbored]

@niccokunzmann I don't think conversions are reliable. Currently, sphinx now supports markdown with an external "parser".

[yukiisbored]

I'm thinking about terminating README.md completely just because GitHub and Sphinx uses them and it causes confusion for newcomers.

[Serkan-devel]

mkdocs uses markdown