launchpad-dev team mailing list archive

[Bjorn Tillenius <bjorn@xxxxxxxxxxxxx>]

Some time ago we discussed what the architecture vision/overview should
contain. I now have a first draft, ready for review. The easiest way of
looking at it is to go to:

    http://people.canonical.com/~bjorn/lp-architecture/

To contribute and take a closer look at how it looks like, please check
out this branch (although I'll soon merge it into trunk):

    lp:~bjornt/launchpad/architect-vision

I'm looking for comments, as to whether this was something that you had
expected, and if you think this would be useful, both in the POV of you,
and new developers. I'm also looking for volunteers to document the
various components we already have :) You can find most of the missing
pieces to be documented in index.rst.

A couple of comments on how it's structured at the moment. There are
currently three parts, Basics, Components, and In-depth. The first two
ones are the most important ones. "Basics" gives and overview of the
architecture, and it's worth reading the "Guiding Principles of the
Architecture". This is meant to be a checklist of what properties a
component of the architecture should have. If some component doesn't
have this properties, it means it's something we should fix.

The second part, Components, lists and documents all the different
components in the architecture. My goal is for that documentation to be
quite light weight. It should document what a component is used for, and
how to use it. It shouldn't go into too much detail. That's why I don't
list all the methods/attributes in a class/interface, I only list the
most important ones.

For details, I added the third section, In-depth. The current
documentation just a symlink to an existing doctest in our tree. I'm not
sure how to structure this section in the tree itself. It might make
sense to create a new documentation tree for this.

You'll also note that I've used Sphinx's autodoc module. This pulls in
existing docstrings from methods and classes. I think this is good,
since the docstrings should provide good documentation, since this means
that people looking at the code itself will have an easier time
understanding. This means that documenting a component isn't only about
writing new ReST documents, it's also about improving existing
docstrings.

There are some things that haven't been done yet (and I'm looking for
volunteers for these tasks as well!). The documentation contains some
examples, but we don't run the currently as tests, so we don't know
whether they work. Also, pulling in docstrings from interfaces doesn't
work that well. We've tried using repoze.sphinx.autointerface, but it
supports only pulling in all the interface, not parts of it. Until that
is fixes, I've simply copy&pasted docstrings, which is less than ideal.



-- 
Björn Tillenius | https://launchpad.net/~bjornt