Add ready-to-build docs folder with the mkdocs tool

[Javi]

Fixes #196
In order to build the site for uploading (to GH pages for example) or serving locally, you need to run mkdocs, which is available from brew, apt-get, choco and others.

From then, mkdocs serve will host the site locally, and mkdocs gh-deploy compiles the site and pushes it to the gh-pages branch.

Currently the user guide looks like this:

And the first iteration of the analyser looks like this:

Some known things to improve on:

• Depend on mumuki-styles and the JSON viewer instead of having a drop-in
• Add a rich text editor to the spec textarea (maybe Ace?)
• Improve styles and copy
• A few small code refactors such as separating the analyser into another puse html file

[Javi]

I've made the input monospaced as it should have been in the first place, thanks to @rodri042 for the tip!

[flbulgarelli]

I love it! I will test it locally and share my thougths.

[flbulgarelli]

@Javi I couldn't start the server. I got the following:

INFO    -  Building documentation... 
WARNING -  Config value: 'nav'. Warning: Unrecognised configuration name: nav 
ERROR   -  Config value: 'theme'. Error: Unrecognised theme. 

Aborted with 1 Configuration Errors!

Which mkdocs version are you using? Could you provide more installation instructions, please?

[Javi]

Should be fixed now! Also added instructions to top post:

mkdocs serve will host the site locally, and mkdocs gh-deploy compiles the site and pushes it to the gh-pages branch.

[flbulgarelli]

In addition to the improvements already mentioned, I'd add some kind of explanation and/or samples of what you can actually try. Perhaps a combo with a list of samples ready to be copied on the editor.

Also, it would be nice to be able to have an additional simplified try-it for just coding a program and selecting the language, and generating the AST.

[flbulgarelli]

Also, we should stop copying mulang.js and instead deploying it as a npm package

[flbulgarelli]

Depend on mumuki-styles and the JSON viewer instead of having a drop-in

I don't see any native npm/bower support for mkdocs at first glance. Perhaps we could have a docs/devinit like the following pseudo-bash-code:

echo "[Mulang::Docs] Cleaning up resources..."
rm docs/js/mulang.js
rm docs/js/mumuk-styles.js
rm docs/css/mumuki-styles.js

echo "[Mulang::Docs] Installing mulang.js..."
wget https://github.com/mumuki/mulang/releases/download/v4.2.0/mulang.js.zip | unzip > docs/js/mulang.js

echo "[Mulang::Docs] Installing mumuki-styles..."
wget https://raw.githubusercontent.com/mumuki/mumuki-styles/master/dist/css/mumuki-styles.css docs/css/mumuki-styles.css
wget https://raw.githubusercontent.com/mumuki/mumuki-styles/master/dist/javascripts/mumuki-styles.js docs/js/mumuki-styles.js

echo "[Mulang::Docs] Building the docs for first time..."
mkdocs build

echo "[Mulang::Docs] Done! Now run mkdocs serve"

[Javi]

@flbulgarelli Is there a published npm version of Mulang?

[flbulgarelli]

@flbulgarelli Is there a published npm version of Mulang?

yes! Check here https://www.npmjs.com/package/mulang

Usage:

$ npm install mulang

const mulang = require('mulang');
> mulang.analyse({
       "sample" : {
            "tag" : "CodeSample",
            "language" : "Haskell",
            "content" : "x = 1"
         },
       "spec" : {
            "smellsSet" : { "tag" : "NoSmells" },
            "expectations" : [
               {
                    "binding" : "*",
                    "inspection" : "Declares:x"
                 }
            ]
         }
    })
{ signatures: [],
  smells: [],
  expectationResults: [ { expectation: [Object], result: true } ],
  tag: 'AnalysisCompleted',
  intermediateLanguage: null }

[flbulgarelli]

I have just pushed JS compiled version for 4.5.2. We should update this PR.

[flbulgarelli]

Also, we should put the docs in sync with current readme

[flbulgarelli]

I have just removed cinder from source control. We should do the same with json-viewer

[flbulgarelli]

Pending tasks:

• bug in position.foo sample
• Add better try samples ✔️
• Add EDL samples ✔️
• Use EDL formatter ✔️
• Improve shortcuts in Ruby implementation. See Feature improved ruby interface #247 ✔️
• Improve shortcuts in JS implementation✔️
• Include 18n in Ruby implementation. See Feature improved ruby interface #247 ✔️
• Document matchers ✔️
• Document Hackage removal. See Hackage deploy is failing #159 ✔️

[flbulgarelli]

Deployed site with current changes