Add auto generated docs

[saulshanabrook]

I have added support for building docs with codox.

In order to get this working, you need to:

1. Add a github API token to Travis as a secret variable, so that it can push the gh-pages branch to your repository when it generates the docs. You can add the variable here. It should be named GITHUB_TOKEN and the value should be the token. To generate a new token, go here. You can give it any description and it only needs the "public_repo" checked, because it just going to be pushing to this repo.
2. Merge this pull request.

They are currently working on my fork:

[thelmuth]

This looks great!

[saulshanabrook]

@lspector Did you set the GITHUB_TOKEN in travis?

[saulshanabrook]

@lspector Once you do step 1, you have to restart the build. Go to the build page and click the little circle arrow thing to restart the build. Lemme know if you have any troubles.

[lspector]

@saulshanabrook I don't know if this counts as having troubles or if it's what you expected, but the build process ended with Done. Your build exited with 0., which appears to stem from the failure of lein test (for reasons we have discussed). I don't know what state this leaves things in or what I should do next. I see that I've received another pull request (add lein check to travis (#168)) but I won't act on that until I hear from you.

[saulshanabrook]

@lspector exit code zero is good! 😄 Any non zero exit code means the command errored. Travis just runs very command, and uses the exit code to determine whether it failed or not.

Docs are now working! http://lspector.github.io/Clojush/

[saulshanabrook]

You will notice also there is a "view source" button next to all functions, that will you take you to the source on the master branch for that function.

[thelmuth]

Looking great!

I noticed that a lot of the problem files aren't appearing in the docs, including almost all of the software problems. Is this because of conflicting function name errors, or something else?

[saulshanabrook]

@thelmuth Yeah I had noticed this. Looking in the logs:

Could not generate clojure documentation for clojush.problems.boolean.mux-6 - root cause: clojure.lang.Compiler$CompilerException java.lang.Exception: Duplicate Push instruction defined:a0, compiling:(clojush/problems/boolean/mux_6.clj:40:1)
[...]
Could not generate clojure documentation for clojush.problems.boolean.rule30-dynamic - root cause: clojure.lang.Compiler$CompilerException java.lang.AssertionError: Assert failed: Instruction d3 does not have :stack-types defined in metadata.
[...]
Could not generate clojure documentation for clojush.problems.classification.intertwined-spirals - root cause: clojure.lang.Compiler$CompilerException java.lang.RuntimeException: Unable to resolve symbol: instr-paren-requirements in this context, compiling:(clojush/problems/classification/intertwined_spirals.clj:86:1)
[...]
Could not generate clojure documentation for clojush.problems.control.dsoar - root cause: clojure.lang.Compiler$CompilerException java.lang.IllegalStateException: recognize-literal already refers to: #'clojush.util/recognize-literal in namespace: clojush.interpreter, compiling:(clojush/problems/control/dsoar.clj:27:1)
[...]
Could not generate clojure documentation for clojush.problems.demos.odd-csv-and-json - root cause: clojure.lang.Compiler$CompilerException java.lang.ClassNotFoundException: clojush.problems.demos.odd, compiling:(clojush/problems/demos/odd_csv_and_json.clj:17:3)
[...]

This is a result of side effects happening when certain files are loaded. In order to perform more comprehensive doc generation and linting, we need to eliminate those. I just opened #169 to track this.