Documentation revamp

[drvinceknight]

I think that the documentation needs a lot of work. It doesn't really serve it's purpose. This is a relic of my initial poor contribution and then a process that built on that by incrementally adding to it.

The only way to understand the library is to read (and remember) the documentation from start to finish. This is because the documentation is a mix/hybrid of a tutorial and a reference document.

My suggestion is along the lines of the following:

• tutorials should be short compartmentalised how to guides
• references should explain what things do but again be compartmentalised and follow the code base
• the final aspect of the documentation is the more 'historical' side: the history of the tournament, the basics of the game theory, the mathematics behind moran processes etc... This is relatively ok I think in the library at present (with some things not in yet).

So I would suggest the docs file structure would look something like:

|-- docs/
     intro.rst
     |-- reference
          |-- tournament.rst
          |-- player.rst
          |-- strategy.rst
          ...
     |-- tutorials
          |-- basic_tournament.rst
          |-- ecological_tournament.rst
          |-- noisy_tournament.rst
     |-- backround # for want of a better word? 
          |-- axelrod_first_tournament.rst
          |-- axelrod_second_tournament.rst
          |-- theory_of_repeated_games.rst
          |-- index_of_strategies.rst

This would have the advantage of people being able to write new tutorials/references when new things are included. Basically everything becomes modular.

Another important thing I think we should ensure is doctesting the docs. Then have a script that we run to run tests and finally ensure this is on travis. The main reasoning behind this is to ensure that any changes in the code are tested in the docs.

If everyone thinks this is a long the right lines I'd like to pick an initial stab up :)

[marcharper]

Sounds good to me, I presume this subsumes #140, #199, and perhaps #225?

[drvinceknight]

It certainly does for #140 and #199 (have closed them). Will leave it up to you for #225, in a way that is kind of an 'ongoing mission'...

[marcharper]

We could pull in some of the stuff from my AxelrodExamples repo, like the example tournaments, with more explanation and a narrative of course. In particular, duplicating the S&P tournament (and perhaps Tyler's tournament) make sense in line with the goals of the project (IMO). Maybe under a "reproducing tournaments" section?

[drvinceknight]

In particular, duplicating the S&P tournament (and perhaps Tyler's tournament) make sense in line with the goals of the project (IMO). Maybe under a "reproducing tournaments" section?

If I understand you correctly I think that sits really nicely under my suggested tutorials section? So as well as a 'getting started' tutorial there could be a 'duplicating the S&P tournament' tutorial? Does that match what you're suggesting?

In essence the tutorials would be plugins, interesting ones could be thrown in...

[drvinceknight]

Tagging #318 here as it's relevant (and #318 make me really sad...).