On Aug 3, 10:44 pm, Serhiy Oplakanets <
ser...@oplakanets.com> wrote:
> I want to also try sphinx and then make my mind. My first evaluation of Sphinx wasn't that successful. Comparing to Javadoc it looked like black magic to me :)
Thats apples and oranges ;) Sphinx is about writing documentation with
a bit of embedded code documentation from python docstrings. So you
can write about when() and have a nice link to the documentation (and
source code) of the when function. Javadoc just creates API docs from
the docstrings (or whatever they're called in Java world). The
equivalent to Javadoc would be ePydoc, Sphinx is a bigger thing... For
Java itself, there is the API docs, but theres also other things as
the Java Tutorials site at Oracle because Javadoc just isn't the right
tool to generate user-friendly documentation. And thats fine. A
detailed tutorial of a complex system doesn't belong in a docstring.
Also its not that important where the project is hosted. Just make
sure it is easy for users to identify the official, "master" home
page. No one (okay, no developer which is your target audience ;))
cares if thats a nice homepage (like lettuce ;)), a google code or
bitbucket page. Just make sure it is the first hit on google and it
provides links to the official bug tracker and the most recent code.
This is a problem with many projects since DCVS gained so much
popularity (which is a good thing): Users don't know where to get the
latest code and don't know where to drop comments, feature requests
and report bugs - and that hurts the project.
Chris