WIP: Add docs using Documenter.jl

[shizejin]

Suggested by #25 and QuantEcon/QuantEcon.jl#136 .

Here I wrote a script "auto_doc_gen.jl" to generate markdown files which is needed for Documenter.jl to create docs. It reads src/Games.jl and finds out which Julia files are included in it, and then write makrdown file for each respectively.

I also tried auto-deployment through Travis, following Hosting Documentation and what @sglyon did in QuantEcon.jl. Here is what I auto-deployed on my forked repo, so you can see how the output will look like. Especially, I modified docstrings of one Method of NormalFormGame to the format suggested by Julia, and we can compare with our currently used doctrisngs, to see whether we would like to adopt this style. (This change is only in my forked repo, no in this PR).

One problem happens, that tests for Games.jl can not pass, which causes build on Travis to fail and nothing is pushed to repo by Documenter.jl. For now I disenabled tests "test_normal_form_game.jl" and "test_repeated_game.jl" in my forked repo to avoid build failure, while I don't think it's a good way.

In details:

1. For "test_normal_form_game.jl", failures happen as discussed in Type stability #2 .
2. For "test_repeated_game.jl", build errors of CDDLib.jl happens on linux. For osx, it's fine.

It would be great if you would like to give some comments or suggestions.
@oyamad @sglyon @cc7768

[sglyon]

@shizejin this is great! Thank you for working on it.

One thing that would be great is to add to this manual a User Guide section before the Library section that is more expositional in style and shows examples of how to work with the library. Using the examples in existing notebooks we have floating around would be a good place to start.

[oyamad]

This looks very impressive.

It will be nice if you add a description to docs/README.md about how to use auto_doc_gen.jl.

[oyamad]

Can you post the build errors for CDDLib.jl at gist?

[oyamad]

Is this the error log? gmp is missing there.

Maybe you need these lines?

[shizejin]

Yes! This is the error log. I haven't known that Travis log could be accessed by others and was trying to find some way to share it... Anyway, this solves CDDLib.jl build error perfectly, thank you so much!

[sglyon]

Do we have travis set up on this repo?

[sglyon]

I don't think we did. I just activated it.

@shizejin I think I will also need to add the documenter key to travis as an environment variable so the docs will build, is that right?

[shizejin]

We are talking about travis log on my forked repo.

Exactly. We need to add keys for both this repo and travis.

[sglyon]

Got it, I just want to make sure that when this PR is merged things are all set up here to work properly.

Can you tell me what steps you went through to get travis to build docs on your repo?

[shizejin]

The make.jl file and .travis.yml are both set ready for generating docs. What left for us to do is to add keys following this and create gh-pages branch.

I suggest we resolve the test failure of test_normal_form_game.jl before we merge this PR, or just suppress it in this stage. Otherwise Documenter.jl won't start to work.

BTW, I am setting OSX Julia 0.5 Travis build bot to deploy the docs. Now that the CDDLib.jl build error is solved ,linux build bot is also available. Do we have preference on the OS and Julia version?

[sglyon]

Getting tests to pass before merging would be great.

I think we should use the linux bot julia 0.5 for docs.

[shizejin]

Got it, I will change make.jl right now.

[oyamad]

See #28 for the test errors from @inferred.

[oyamad]

"Julia: release" and "Julia: 0.5" look the same in here. One of them should be deactivated.

[sglyon]

Agreed. Let's deactivate release and stick to version numbers and (potentially) nightly

[shizejin]

As professor @oyamad suggested, it might be convenient to arrange files in sections, e.g. pure_nash.jl and support_enumeration.jl should be included in the same section "Computing Nash equilibria". I modified auto_doc_gen.jl and added a file called Structure so that we could arrange the structure more flexibly. (more details here)

Here is an example I deployed on my forked repo. I've tested adding support_enumeration.jl with and without setting its section, and it worked fine.

[oyamad]

Let's merge this to see how it will look.