OK guys, good news. We now have a documentation framework! So we should now start documenting the particularly hairy parts of the system, as well as giving an architectural overview. I did it now because Prageeth wrote some documentation on the data wrapper question<https://answers.launchpad.net/mugle/+question/148518>which really belongs in the architectural documentation, so I wanted to start.
I have chosen Sphinx <http://sphinx.pocoo.org/>, which is the Python documentation system. I have used it for Mars<http://ww2.cs.mu.oz.au/%7Emgiuca/mars/docs/>(not a Python project) and IVLE <https://ivle.googlecode.com/svn/doc/sphinx/index.html> so I'm very confident in its ability to easily document software, in any language, and produce very pretty output as well. So I have checked in to the trunk a 'doc' directory (the old doc directory was moved to 'design'). The new 'doc' directory is now just for Sphinx. You should install Sphinx (apt-get install python-sphinx) and then you can cd to the 'doc' directory and type 'make html' to build the docs. They will then be available in doc/build/html/index.html. You need to type 'make html' every time you change the docs. So I have separated the docs into four sections: one for users, one for game developers, one for admins, and one for platform developers. Don't worry too much about the first three -- we can document those later on (but if we write any APIs which we are exposing to game developers, we should document those in the game developers section). I want to get started documenting the internals, though, because otherwise we'll forget some of these details. Prageeth: I merged the docs into your data-wrapper branch, because I wanted to incorporate your data-wrapper documentation (which is only relevant to that branch). So I did that, then inside the branch, I created a data-wrappers page, and added your documentation all Sphinxed up. Take a look; this is a good example of some documentation: data-wrappers.rst<http://bazaar.launchpad.net/%7Emugle-dev/mugle/data-wrapper/view/head:/doc/platform/data-wrappers.rst>. The language used is ReStructured Text (RST) which is a fairly lightweight markup language. To write normal paragraphs, you just write them as in a text file. There is some weird syntax for headings and also code samples. If you compile the documentation, you will notice that the code samples are nicely highlighted as Java code. Let me know if you have any questions about the documentation.
-- Mailing list: https://launchpad.net/~mugle-dev Post to : [email protected] Unsubscribe : https://launchpad.net/~mugle-dev More help : https://help.launchpad.net/ListHelp
