mugle-dev team mailing list archive

[Matt Giuca <matt.giuca@xxxxxxxxx>]

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.