proposal for online documentation

[mdipierro]

I got a private email from David and we have an idea:

1) organize a wiki with the same table of content as the book. Each
page will have an errata and a a faq. It will include some parts of
the book (when possible) and link the scribd book chapters when not
possible.

2) integrate the above with a small web2py app that turns web2py
docstrings into wiki pages. When users edit the wiki, the docstrings
get updated, and I get a patch.

What do people think?

Massimo

[tiago almeida]

Hi!

1) Great idea.

2) Wouldn't the docstrings get immensely complex for someone actually reading/mantaining the code? Maybe a Sphinx approach to code documentation would be better.

Best regards,
Tiago

--
You received this message because you are subscribed to the Google Groups "web2py-users" group.
To post to this group, send email to web...@googlegroups.com.
To unsubscribe from this group, send email to web2py+un...@googlegroups.com.
For more options, visit this group at http://groups.google.com/group/web2py?hl=en.

[Jonathan Lundell]

On Feb 5, 2010, at 8:11 AM, mdipierro wrote:

> I got a private email from David and we have an idea:
>
> 1) organize a wiki with the same table of content as the book. Each
> page will have an errata and a a faq.

I'd been thinking of that myself (so it must be a good idea!).

> It will include some parts of
> the book (when possible) and link the scribd book chapters when not
> possible.

Perhaps each wiki page could always link to the appropriate chapter/section, so it's always available for reference.

>
> 2) integrate the above with a small web2py app that turns web2py
> docstrings into wiki pages. When users edit the wiki, the docstrings
> get updated, and I get a patch.

Interesting thought. I'm slightly skeptical (about editing docstrings outside the context of the source code itself, and about doctests), but at the very least the underlying goal is great: a way to quickly edit docstrings without going through a formal patch process.

>
> What do people think?

[mdipierro]

> > 2) integrate the above with a small web2py app that turns web2py
> > docstrings into wiki pages. When users edit the wiki, the docstrings
> > get updated, and I get a patch.
>
> Interesting thought. I'm slightly skeptical (about editing docstrings outside the context of the source code itself, and about doctests), but at the very least the underlying goal is great: a way to quickly edit docstrings without going through a formal patch process.

The way it would work is that a program moves docstring from gluon to
wiki. People edit the wiki with versioning. I can review them and have
a mechanism to automatically put them back.

I yet do not know how to implement the last step. It would help if I
could find example of code that automatically replaces some text ('a'-
>'b') inside all docstrings. It would help me build the app.

[Zoom.Quiet]

On Sat, Feb 6, 2010 at 00:26, tiago almeida <tiago.b...@gmail.com> wrote:
> Hi!
>
> 1) Great idea.
>
great +1

> 2) Wouldn't the docstrings get immensely complex for someone actually
> reading/mantaining the code? Maybe a Sphinx approach to code documentation
> would be better.
>

when collection ebough doc in wiki,
and, understand who to make book in Sohinx though web2py ,
we can move in...
such as :关于本书的编写 — 用Python做科学计算
http://hyry.dip.jp/pydoc/pydoc_write_tools.html
custom sphinx plugin comment action ...

--
http://zoomquiet.org 人生苦短? Pythonic!
一个人如果力求完善自己,就会看到:"为此也必须同时完善他人. 一个人如果不关心别人的完善,自己便不可能完善!"

[Jason Brower]

I also agree, then we create a dynamic and growing collection of
documentation and when I need the information from the book I can get it
there as well. Very fun idea indeed.
BR,
J

[selecta]

1) ok, i got the book, but 2 resources are better then one, people
explain differently so it will help to have a second source

2.0) love the idea :) exactly my thought ....,
also i would split the docstring into multiple sections:
a) (short) description,
b) explanations of input and output variables (epydoc syntax)
c) unit-tests

2.1) i would extend the docstring wiki by an example/comments part
below the wiki page that will not be merged with the code because e.g.
a validator would be hard to understand with just a docstring

[Werner F. Bruhin]

What about reuse?

E.g.:
http://tosh.pl/gminick/gsoc/sphinx/

Werner

[mdipierro]

I am not sure if this does exactly what I mean (can you actually edit
and version docstrings and put them back in code?). Anyway, it would
be nice it somebody where to set this up as an example for web2py.

[weheh]

I can't comment technically on the idea of converting docstring to
wiki pages, although it sounds good. The problem with doc that I think
needs solving, however, is that of not being able to easily find items
in the doc. The v2 doc index is missing a ton of links -- really
important thinks like onvalidation or SQLFORM.factory ... are
curiously absent. If the wiki provides a more linked way to get at
that information, the count me +1.

[Werner F. Bruhin]

On 05/02/2010 18:52, mdipierro wrote:
> I am not sure if this does exactly what I mean (can you actually edit
> and version docstrings and put them back in code?).

I don't know, but as Sphinx gets doc from the doc strings I would assume so.

Anyway, it would
> be nice it somebody where to set this up as an example for web2py.

Maybe check with the author/student where he is with the project and
explain what you would like to see.

Werner

[Thadeus Burgess]

I still think documenting the source code is the first step, then from
that we can build a wiki/faq/walkthrough off of it. But gluon/* needs
to be documented thoroughly before we do anything else.

We should instead be discussing a method/style of documenting gluon,
and then putting resources towards it. This will help by making web2py
much easier for contributors to actually contribute. Once there is
ample amounts of documentation in the source code, then we can begin
migrating things to the wiki using an automatic system. Even werkzeug
has very nice documentation that has two versions, one compiled from
the last developmental commit, and one from the last stable commit.

I have an extremely strong opinion about the following. Source code
documentation should NOT be editable through a wiki. I do not like
this idea. It does not seem safe. I would only trust the source
documentation to those who contribute source code.

-Thadeus

[mdipierro]

The wiki would only be a way to make it easy for people to contribute.
I agree we need guidelines. page would be into parts (proposed edit
to the actual docstrings, annotations, comments). Changes to actual
docstrings would still need to go though the approval process.

Please share with us any thoughts about guidelines for docstrings.

On Feb 5, 1:01 pm, Thadeus Burgess <thade...@thadeusb.com> wrote:
> I still think documenting the source code is the first step, then from
> that we can build a wiki/faq/walkthrough off of it. But gluon/* needs
> to be documented thoroughly before we do anything else.
>
> We should instead be discussing a method/style of documenting gluon,
> and then putting resources towards it. This will help by making web2py
> much easier for contributors to actually contribute. Once there is
> ample amounts of documentation in the source code, then we can begin
> migrating things to the wiki using an automatic system. Even werkzeug
> has very nice documentation that has two versions, one compiled from
> the last developmental commit, and one from the last stable commit.
>
> I have an extremely strong opinion about the following. Source code
> documentation should NOT be editable through a wiki. I do not like
> this idea. It does not seem safe. I would only trust the source
> documentation to those who contribute source code.
>
> -Thadeus
>

[Richard]

> 2) integrate the above with a small web2py app that turns web2py
> docstrings into wiki pages. When users edit the wiki, the docstrings
> get updated, and I get a patch.

I proposed something like this earlier, so definitely agree.
http://groups.google.com/group/web2py/browse_thread/thread/231fee7e4a11682d/5f70efc0edf23226?q=#5f70efc0edf23226

[JonasR]

Great idea!

I agree with selecta on 2.1.
To have examples and comments would be the most valuable part IMHO.
Documentation can be found today, even if it is spread around. But the
big difference would be if people could contribute with examples and
comments close to the documentation. That would make it much faster to
find relevant information.

/ jonas