Create a nice web documentation of GTG functions

[Luca Invernizzi]

Several potential developers come by IRC or mail someone in the team, interested in helping out with gtg.
However, we are not extremely easy to hack into for unexperienced developers: therefore, we are losing patches.

I think we should write a simple guide for that, and generate a web documentation of our functions (via http://docs.python.org/library/pydoc ? I'm not an expert on this matter).
That should make things seem more easy.

[Luca Invernizzi (invernizzi)]

For the "simple guide for new devs" part, I'm starting to draft one in the blog. Anyone is welcome to join. Should it go in the wiki instead? On both? Comments appreciated.

[Bryce Harrington (bryce)]

On Tue, Feb 23, 2010 at 01:25:09AM -0000, Luca Invernizzi wrote:
> For the "simple guide for new devs" part, I'm starting to draft one in
> the blog. Anyone is welcome to join. Should it go in the wiki instead?
> On both? Comments appreciated.

Wiki would be better for those of us likely to contribute but without
rights to update the blog. :-)

Really, the blog should just give a terse/encouraging intro and then
point at the wiki for the real deal.

[Luca Invernizzi (invernizzi)]

Good point. Link http://live.gnome.org/gtg/easyguide . It is not yet linked from the main gtg wiki page, since it is a work in progress.
We do have something similar http://live.gnome.org/gtg/contributing, but I was thinking about making it very easier and friendlier (groundcontrol, ...)

[Alexandre COLLIGNON (alexandre-collignon)]

Sounds good ! I'm interested in helping you.
Moreover, I can translate this doc in French if you think that it could be useful.
---
Alexandre COLLIGNON

Le mar 23/02/10 01:52, Luca Invernizzi <email address hidden> a écrit:
> Good point. Link http://live.gnome.org/gtg/easyguide . It is not
> yet linked from the main gtg wiki page, since it is a work in
> progress.
We do have something similar http://live.gnome.org/gtg/contributing, but
> I was thinking about making it very easier and friendlier (groundcontrol,
> ...)
> --
> Create a nice web documentation of GTG functions
>
> https://bugs.launchpad.net/bugs/526150
You received this bug notification because you are a member of Gtg
> contributors, which is subscribed to Getting Things GNOME!.
>
> Status in Getting Things GNOME!: Confirmed
>
> Bug description:
> Several potential developers come by IRC or mail someone in the team,
> interested in helping out with gtg.
However, we are not extremely easy to hack into for unexperienced
> developers: therefore, we are losing patches.
> I think we should write a simple guide for that, and generate a web
> documentation of our functions (via http://docs.python.org/library/pydoc ? I'm not
> an expert on this matter).
That should make things seem more easy.
>
>
>
>
>

[Lionel Dricot (ploum-deactivatedaccount)]

I don't believe it's useful. While we should lower the barrier as much as
possible to allow new contributors to come in, we also expect new
contributors to have a minimum knowledge. People that never wrote a line of
python should start from the beginning.

Also, I personally expect all contributors to be able to communicate in
english and to read english documentation. If this is not the case, then
the potential contributor simply don't have the minimum level to start
contributing and trying to get him in the project would be a complete waste
of time for us and for him too. It will also mean that that particular
person would not be able to take part in the GTG community !!!

People who want to contribute to GTG should be able to communicate in
english, have programmation knowledge a minimum python experience. We will
not document what an object is in our documentation !

On Tue, 23 Feb 2010 08:32:39 -0000, Alexandre COLLIGNON
<email address hidden> wrote:
> Sounds good ! I'm interested in helping you.
> Moreover, I can translate this doc in French if you think that it could
be
> useful.
>

[Luca Invernizzi (invernizzi)]

Hi Lionel. I am aware of a lot of people that know how to program but don't have a clue about how to contribute to an open source project.
I don't want to tell them how to program.
I want to explain how to get the code, where the documentation for the plugin api is, and how to do a merge request.

This way, when a person comes by in IRC and ask about how to contribute, I can direct him to the guide. Maybe one in ten will actually submit code, but it's worth trying.

After all, I'm contributing to gtg thanks to http://live.gnome.org/gtg/contributing , which is "lowering the barrier". I simply don't think that bzr is an absolute requirement for the first merge request. I may be wrong, but it doesn't cost much to try.

[Luca Invernizzi (invernizzi)]

That's my idea http://live.gnome.org/gtg/easyguide . If you think it's too "lower bound", I will trash it without problems.

[Lionel Dricot (ploum-deactivatedaccount)]

That's fine, I was only talking about translation. Of course, bzr and
stuffs like that are not requirements.

Speaking English and Python are.

On Tue, 23 Feb 2010 09:31:31 -0000, Luca Invernizzi
<email address hidden> wrote:
> Hi Lionel. I am aware of a lot of people that know how to program but
> don't have a clue about how to contribute to an open source project.
> I don't want to tell them how to program.
> I want to explain how to get the code, where the documentation for the
> plugin api is, and how to do a merge request.
>
> This way, when a person comes by in IRC and ask about how to contribute,
> I can direct him to the guide. Maybe one in ten will actually submit
> code, but it's worth trying.
>
> After all, I'm contributing to gtg thanks to
> http://live.gnome.org/gtg/contributing , which is "lowering the
> barrier". I simply don't think that bzr is an absolute requirement for
> the first merge request. I may be wrong, but it doesn't cost much to
> try.

[Paul Natsuo Kishimoto (khaeru)]

For documenting the code itself, I have some experience using Sphinx (http://sphinx.pocoo.org), the same tool that is used for the actual Python docs.

You do need to maintain a separate tree with some .rst files, but it does a very good job of pulling docstrings out of code, classes and functions and displaying them. Maybe this is a good option to help new developers explore & understand the GTG source.

[Bryce Harrington (bryce)]

For code documentation, the codebase already has PyDoctor support, just do 'make apidocs' from the base directory. I've been adding documentation to the GTG functions and using the web docs on my local (non-public) web server as reference.

Perhaps if we had those docs online, that could be considered a solution to this bug report? Is it possible to have 'make apidocs' cronned hourly on our webserver?

[Bryce Harrington (bryce)]

The pydocs are available at http://allievi.sssup.it/GTG/ so I'm going to boldly assume that solves this particular bug.

We also have better newbie docs as well. Probably could benefit from a few more tutorials, but guess we can attack those as the needs present themselves, no need for bug reports to track it.