graphite-dev team mailing list archive

[Chris Davis <chrismd@xxxxxxxxx>]

Hi everyone, I wanted to let you know about a fantastic new site called
readthedocs.org, they provide free and awesome documentation hosting. While
the wiki is still a valuable resource for general purpose info, I am
planning on writing the documentation all for readthedocs.org. Part of why
they're awesome is that they use Sphinx, which uses reST. Writing reST in vi
is way more enjoyable than writing (non-portable) wiki markup in a textarea.
Plus all the documentation lives in bzr. Sphinx makes it easy to generate
developer documentation because it can be built dynamically from
docstrings... all we need now is some docstrings :)

I've put together a rough (and incomplete) outline of the user
documentation. It is almost all stubs at the moment, but it at least serves
as a roadmap/todo list for future documentation work. Once the user
documentation is at a satisfactory level I will embark on writing some real
developer documentation. A few brave souls have learned the completely
undocumented codebase enough to make some awesome contributions, and I hope
to ease the pain for them in the future as well as anyone else who wishes to
hack on Graphite.

Also I wanted to let everyone know that we've got an irc channel on
freenode, #graphite. Initially it was pretty empty but now there are pretty
much always 5+ people online, myself included. That is a great place to come
and discuss anything and everything Graphite related. For troubleshooting
issues I would prefer to keep that on the Launchpad questions forums, since
that is readily available and searchable by anyone, etc. Plus it's a nicer
place to share error logs and giant stack traces and the like. That said,
feel free to hop in on #graphite.

On the release planning front, I plan to release Graphite 0.9.8 either this
coming weekend or early next week. It includes several bugfixes and some
really awesome new features (more details to come).

Beyond that, I have been working for several months on a separate branch of
Graphite that greatly improves the clustering model and replaces whisper
with a new database library called Ceres (fear not, making migration easy is
a priority & whisper will still be supported). This is going into my
production environment on Thursday, so if all goes well this branch will
become the 0.9.9 release a couple weeks after 0.9.8 is out.

Here is the new home of Graphite's documentation (bear in mind it is almost
all stubs at the moment):

http://graphite.readthedocs.org/ (also available as
http://graphite.rtfd.org/)

Thanks to Syllogist (http://www.syllogist.net/) for helping to get this
documentation initiative started.

For anyone who wants to help write documentation, grab the latest checkout
of trunk and look in the new 'docs' folder. You can learn about writing
documentation with Sphinx here (http://sphinx.pocoo.org/rest.html). If you
make changes, you can build the docs locally using "make clean html". Once
you're happy with your changes you can commit them. ReadTheDocs.org will
automatically rebuild the hosted documentation nightly, but you can kick off
a build immediately by hitting this url:
http://readthedocs.org/build/534(this only works if you're changes are
committed to trunk)

Please feel free to commit any documentation you'd like. Seriously. Whether
it's good, bad, or even ugly. I may edit & reorganize here and there but in
general, the more the merrier.

As usual, let me know if you have any questions / comments / etc.

-Chris