Switch to mkdocs

[andre2007]

I did some closer look on mkdocs as tool for generating a nice documentation site for intellij-dlanguage.

An example page created with mkdocs you can see here:
http://opensciencegrid.org/security/

The concept is rather easy. On master branch you write the markdown files. There is a second branch gh_pages which contains the generated documentation based on the markdown files.
A travis CI job automatically creates and upload the files to the gh_pages branch on push to master branch.

Setting up travis ci is described here
https://djw8605.github.io/2017/02/08/deploying-docs-on-github-with-travisci/

[SingingBush]

I'm open to using mkdocs. As this is a organization page though there's no gh_pages branch, we just push to master.

[andre2007]

I am not sure what you mean with organization page. I think 2 branches are necessary:

• master: contains the source code (the markdown files). Merging pull requests into master triggers the Travis CI job to compile(translate) the markdown files into html files
• gh_pages: contains the generated html files. https://intellij-dlanguage.github.io/ will point to the gh_pages branch

Maybe it is possible to have the markdown and the generated html files in 1 branch (master) but then you have to invest more time into the travis CI logic. Pushing the generated html files should not trigger the mkdocs process again -> endless loop

[andre2007]

I started to create a mkdocs prototype. Unfortunately the actual version of mkdocs has a bug while deploying to User/Organization pages. mkdocs/mkdocs#1525
This bug will be solved with next version of mkdocs. I assume version 0.17.6.
When the version is available I will continue working on this topic.

[waylan]

This bug will be solved with next version of mkdocs. I assume version 0.17.6.

Not version 0.17.6, but version 1.0. This was not a bug with a simple bugfix. Previously, MkDocs did not support User/Organization pages. To add support, we needed to make a backward incompatible change to how relative paths in the config file are resolved (see mkdocs/mkdocs#1376 for details). Therefore, this change will be part of a major release.