Improving documentation

[ftomassetti]

In this issue we could discuss how to improve documentation. I think it could be also a good exercise to take a step back and look at the global picture so that we can shape how we want version 1.0 to be.

I would suggest to use readthedocs: https://readthedocs.org/. To use it we should create a directory containing documentation in a rst format (think of it as an alternative to Markdown) and a git hook will just take those documents, compile them and produce documentation which would be available under worldengine.readthedocs.org

What do you think? @psi29a @esampson @tcld

[tcld]

I don't have experience with writing proper documentation. Are you thinking of a user-side documentation (explain commandline parameters and maybe some scientific foundations) or more of a developer-side documentation (explain functions, return values, etc.)?

[ftomassetti]

User-side documentation: what it is possible to do with WorldEngine. We could need also better developer-side documentation. Perhaps we could use comments in code and the wiki for that.

[ftomassetti]

I woud like to document:

• the single options showing different worlds generated changing the parameters
• typical use cases
  • I want to use WorldEngine as a library from Python
  • I want to use WorldEngine as a library from Java
  • I want to just generate large cool maps
  • I want to import some map and run some simulations in WorldEngine

[esampson]

I can look at tackling the general documentation; things such as what the different options are, what they produce, and explanations of biomes, temperature and humidity ranges.

[ftomassetti]

thanks @esampson that is appreciated. Perhaps we could try to have small PRs for the documentation and merge frequently so it is easier for everyone to contribute. Do you want me to setup readthedocs or do you want to do that?

[psi29a]

RTD is great, but we should really use Sphinx to handle things. I've experience with this, just a bit to setup and it documents itself. :)

[psi29a]

This means that documentation needs to be written in ReST: http://sphinx-doc.org/rest.html

If people want to start doing this, it is trivial to add to Sphinx. RTD then takes Sphinx and generates documentation for us in LaTeX, pdf, HTML and etc...

[ftomassetti]

Cool. We have the manual in master now so we can discuss the content in specific issues. Closing this general one.