Dixi is a wiki app designed for creating and maintaining Ruby software documentation (especially library API docs) collaboratively. It is powered by Ruby, Sinatra, and Git (via Grit).
Dixi is still in early development (as of December 2009), so don't expect anything fancy yet. If you want to help make Dixi the most kickass documentation system ever, please email jacius+dixi at gmail.com or send a message to jacius on github.
You can see and play with a live instance of Dixi at http://dixi.jacius.info/
-
Because automatic doc generators like RDoc can't handle run-time definitions or other metaprogramming techniques used in Ruby.
-
Because embedding your main documentation in your source code makes it really inconvenient for anyone else to contribute to the docs.
-
Because static docs don't allow users to ask questions, make comments, submit corrections, or provide examples.
-
Because regular wikis aren't well-suited for organizing API docs.
-
Developers who want to frustrate and alienate their users by providing crappy, useless documentation.
-
Developers who think a few scattered comments in the source code of their huge, complex application counts as "technical documentation".
-
Developers who love to maintain documentation all by themselves, with no help from anyone else.
You can use the included ri2dixi script (in "bin") to convert RI documentation to the format used by Dixi. Usage is simple:
./bin/ri2dixi -i -o
The script will scan all RI-formatted YAML files in the input directory (and its subdirectories), convert them into Dixi-formatted YAML files, and save them to the output directory.
To output them directly into your Dixi instance, set the output directory to "contents///api/". Or, output them to some other directory, then copy them all to Dixi after checking them.
In the future, there might be a script that can generate Dixi docs for a project from its source and upload them directly to Dixi. Maybe you will be the person to write that script?
Not currently. There will eventually be a way to export docs as HTML, RI, YARD, or stub code with RDoc-style documentation comments.
There are no plans to offer a tool to re-embed the docs back into your real code as comments. The whole point of Dixi is that your docs shouldn't be embedded in your code.
You will need:
- Ruby 1.8.6+ or JRuby 1.4+
- Sinatra 0.94
- Haml 2.2.17
- Grit 2.0.0
- Kramdown 0.2.0
- Shotgun 0.4 (optional, for development mode)
So...
gem install sinatra haml grit kramdown shotgun
There is nothing to install for Dixi itself. Just run it.
Run rake shotgun, then point your browser to
http://localhost:4567/
But it's more interesting to go to, for example, http://localhost:4567/mylibrary/1.0/Foo
Dixi works well (for me) with Phusion Passenger. Follow the normal procedures for setting up a Rack app on your host.
Run rake capconfig to generate a capconfig.yaml file, then edit it
to provide your deployment details (user name, host, etc.).
Then deploy as usual for Capistrano (cap deploy:setup before the first
time, then cap deploy to deploy).
Copyright 2009 John Croisant
Dixi is licensed under the Apache License, Version 2.0. See LICENSE.txt and NOTICE.txt for details.
John Croisant jacius+dixi@gmail.com