web2py Reference Manual -- a call to arms

[weheh]

This is an old request, but I haven't heard anything about it of late
and wanted to keep it alive.

I propose a web2py reference manual where every web2py-native
statement, helper, DAL, auth, settable attribute, ... whatever is in
indexed and every page has sections: description, usage, arguments
list with explanation of each argument, and reference/link to a parent
statement, helper, DAL, etc.

At least, I think a reference should be as good as python's
documentation and possibly better. I imagine this could easily be a
community thing, built by wiki (prefereably a web2py wiki). If we
could all agree to the headings, then we could all choose a couple/few
web2py statements to work on to document. I bet we could have a kick-
ass reference manual built in a matter of weeks without consuming all
of Massimo's time, and preferably as little as possible.

What do you think? Anybody have ideas about how we could do it?

[ra3don]

I like this idea alot, it would be a valuable resource for a beginner
(like me). I think its important that it be wiki-style so that we can
all come in and add our example useages to the statements, helpers,
etc. (like weheh mentioned) so we get a feel for how to use it if
we're stuck.

[Vasile Ermicioi]

I like php manual style, where at the bottom are user contributions

[weheh]

Why not use cube2py as the wiki?
http://groups.google.com/group/web2py/browse_thread/thread/5b8481c48478eed9/29a01260e7d38618#29a01260e7d38618

[mdipierro]

You can but set

plugin_wiki_level=1 to disable embedded widgets for security

On 10 Lug, 10:28, weheh <richard_gor...@verizon.net> wrote:
> Why not use cube2py as the wiki?http://groups.google.com/group/web2py/browse_thread/thread/5b8481c484...

[weheh]

How shall we do the hosting? Who should administer the site? What to
call it? Shouldn't it be under web2py.com/reference_manual or some
such?

[Bruno Rocha]

http://www.pyforum.org/ Pyforum, could be a start!

with little changes and putting it running on Google App Engine.

2010/7/10 weheh <richard...@verizon.net>:

--

http://rochacbruno.com.br

[weheh]

No, I don't think Pyforum is the answer. I am calling for a reference
manual. The existing documentation is slanted a little more towards a
tutorial form. I'm looking for a very dense, concise, and heavily
cross-indexed document/database of web2py statements and their
attributes, along with examples. I don't think a forum format lends
itself to that kind of knowledge base. Consider this group, which acts
as a forum. Many questions have been answered over the years, but the
data are hard to dredge up unless you come up with just the right
query.

On Jul 10, 1:47 pm, Bruno Rocha <rochacbr...@gmail.com> wrote:
> http://www.pyforum.org/Pyforum, could be a start!

>
> with little changes and putting it running on Google App Engine.
>

> 2010/7/10 weheh <richard_gor...@verizon.net>:

[Pepe]

can cube2py run in google app Engine??

if yes: why not run it on GAE to start from??

regards!

Pepe

[weheh]

Pepe, that's exactly what I was thinking. I haven't done anything like
this myself, so I have no experience. However, my assumption is that
should the number of hits get large enough, then whoever sets up the
app will have to start paying Google for bandwidth, etc. I have no
idea how expensive this would get long term. If Massimo supports the
doc, then it would make sense for all of us to chip in to support the
site, yes?

[Kenneth]

I´m intrested in helping setting up a reference manual, I have never
done anthing like this before so help is needed, I´m neither so deep
into web2py yet that I know where to start.

I guess we need to start and agree on three things:

a) type of manual, wiki or "php forum style". I think wiki sounds
better for this as there are so many contributors, I think we get a
better manual, easier to read.

b) hosting, I have never used GAE so no idea what it would cost, on
GAEs page is stated that you get "around 5 million monthly pageviews
for free". Is this enough? If a CentOS box with Python 2.5 and Apache
is better then I might be able to offer a hosting environment at least
to start with.

c) structure of the reference manual, is there somebody how could
start sketching a structure of the reference manual, I don´t think we
need a) and b) to start with sketching.

[ra3don]

One other thing we might consider, as Kenneth said 5 million monthly
page views, we could cut that by providing a download version of the
reference manual, so that us that frequent it aren't racking up on the
page views.

[rochacbruno]

What about having the reference manual divided in 9 apps.

The limit is by app, and a single account can create 9 apps.

One chapter per app.

Sent from my iPhone

[weheh]

Massimo, do you think 5M pageviews would be exceeded in any month for
the time being?

ra3don: I like your idea of a download version. If we pack all into
a .w2p then the downloadable reference manual would be implemented.
Then you could install it on your local machine and access it later,
even if you didn't have an internet connection. Great for coding while
traveling!

Massimo, is the cube2py wiki ready to take on this task on GAE? If
yes, I say we get on with it. We'd need volunteers to setup and
administer.

Once set up, the first order of business would be to develop (wiki
pages, of course) a style guide for the various types of pages in the
Reference Manual. The pages I can think of three types of pages off
the top of my head:

Index pages
- organized alphabetically by function
- organized alphabetically by parameter/attribute (non-statement)
Manual page for web2py function
Manual page for web2py parameter/attributes

[mdipierro]

This issue issue comes up regularly and my answer does not change.

I very much welcome a community effort to have a better documentation.
It was attempted many times before and many times it has failed. It
failed because people think it is a technological issue (which wiki do
we use?) but it is not. The problem is keeping the docs in sync with
code is a pedantic issue and there is not enough motivation.

The problem with the book is that content is copyrighted and I have an
agreement with the publisher. I have already lost $600/month in
revenues from book sales since the book was posted online. This has
not been bade up by donations.

I am in the process of revising the online book online:
- add new sections
- move from markdown to markmin
- include an automatic markmin to pdf (for download)
- make it more friendly to users

As far as I am concerned I need help with docstings, examples in
docstrigns, and more tests.

I will look into the php wiki you refer to.

Massimo

[weheh]

Massimo, I couldn't agree more. This is not a tech issue. It's an
issue of resolve by the community to help build doc. I do not wish to
make more work for you. I may be naive, but I hope for the opposite --
to distribute the doc burden more on the community.

The existing doc v2 is a major improvement over doc v1. But because it
has a tutorial flavor, it is not as suitable for advanced users, IMHO,
primarily because it's hard to locate desired information. Rather than
overhaul it to be a Reference Manual, I think doc v2 should keep it's
current flavor and a separate Reference Manual should be developed by
the community. Reference Manual content should be terse -- UNIX man-
pages-like. It needs to be heavily cross-linked.

The only reason I even bring up the wiki issue is because we do need
an infrastructure and it should enable us to do what we want without
getting into the way. I prefer a web2py wiki because it will serve the
dual purpose of showcasing the technology and providing a convenient
way to download a copy of the Reference Manual. Unless the PDF you are
planning to output is heavily cross-linked, I don't think it will
serve the Reference Manual's purpose of being able to find info
quickly.

[Bruno Rocha]

PHP manual is great, I always use, the information are easy to find, and connections with related subjects are simple, one advantage is that it was written in a way that allows various applications, badges, widgets etc using your content

I think that information in the PHP manual is organized much like a forum, the first post is a detailed explanation, with some examples. < http://www.php.net/manual/en/language.operators.php > The replies below are more examples of different scenarios for the same explained function.

With a good moderation, preventing unnecessary comments for each thread, PyForum http://www.pyforum.org/ could be a great start, may be, changing PyForum to accept Markmin, and a good way for publish live demo examples.

Simply gather a team, and start writing, in this way each person moderates others.

2010/7/12 mdipierro <mdip...@cs.depaul.edu>

--

http://rochacbruno.com.br

[Bruno Rocha]

Look what i am talking about, in action ->  http://www.pyforum.org/pyforum/default/view_topic/507

2010/7/12 Bruno Rocha <rocha...@gmail.com>

--

http://rochacbruno.com.br

[weheh]

Yes, I see it, thanks. I really do not like this format for a
reference manual. Just a personal preference. Sorry.

I do like the PHP index and cross linking, and I do think there are
some good ideas there, but I think a Reference Manual should be less
of a forum and more documentation oriented. In particular, I'm looking
to get away from a linear narrative and go to a very high-density
highly-cross-linked source of information.

On Jul 12, 2:45 am, Bruno Rocha <rochacbr...@gmail.com> wrote:
> Look what i am talking about, in action ->http://www.pyforum.org/pyforum/default/view_topic/507
>

> 2010/7/12 Bruno Rocha <rochacbr...@gmail.com>

>
>
>
>
>
> > PHP manual is great, I always use, the information are easy to find, and
> > connections with related subjects are simple, one advantage is that it was
> > written in a way that allows various applications, badges, widgets etc using
> > your content
>
> > I think that information in the PHP manual is organized much like a forum,
> > the first post is a detailed explanation, with some examples. <
> >http://www.php.net/manual/en/language.operators.php> The replies below
> > are more examples of different scenarios for the same explained function.
>
> > With a good moderation, preventing unnecessary comments for each thread,

> > PyForumhttp://www.pyforum.org/could be a great start, may be, changing

> > PyForum to accept Markmin, and a good way for publish live demo examples.
>
> > Simply gather a team, and start writing, in this way each person moderates
> > others.
>

> > 2010/7/12 mdipierro <mdipie...@cs.depaul.edu>

> http://rochacbruno.com.br- Hide quoted text -
>
> - Show quoted text -

[Jonathan Lundell]

On Jul 12, 2010, at 9:20 AM, weheh wrote:

> Yes, I see it, thanks. I really do not like this format for a
> reference manual. Just a personal preference. Sorry.
>
> I do like the PHP index and cross linking, and I do think there are
> some good ideas there, but I think a Reference Manual should be less
> of a forum and more documentation oriented. In particular, I'm looking
> to get away from a linear narrative and go to a very high-density
> highly-cross-linked source of information.

Right. No reason it can't link *out* to tutorials and such, but it should be a complete reference in itself. (In the case of web2py, linking out is important, since there are so many disparate sources of information floating around.)

This discussion has a tendency to degenerate into a back & forth about choosing tools (or hosts). Massimo's new wiki seems like a natural choice at this point; I have no idea about hosting, though I suppose that GAE would make an interesting demo (a secondary consideration, of course).

[weheh]

Jonathan, thanks for weighing in. I'm with you that the new web2py
wiki should be the platform. Preferably on GAE. Massimo, will it work?
Also, it makes sense to me that this be addressable under www.web2py.com/reference.

[mdipierro]

Why GAE? Is there a performance issue with the current book?

[Jonathan Lundell]

On Jul 12, 2010, at 12:33 PM, mdipierro wrote:

> Why GAE? Is there a performance issue with the current book?

For my part, only because it'd be a prominent demonstration of web2py on GAE. Other than that, it doesn't matter.

[ra3don]

One quick question. What would be the difference between this and say,
the epydoc http://web2py.com/examples/static/epydoc/index.html, other
than this having wiki capabilities. Am i missing something obvious?

[weheh]

@MDP: No reason for GAE in particular other than it's free initially
and because it's a showcase. Any server is good, as long as the url is
something like web2py.com/reference. There is no performance issue
with the current doc.

@ra3don: Epydocs have very little verbiage and is indecipherable to
the average user, IMHO.

[ra3don]

Yeah i noticed its a little hard to comprehend sometime if you have no
idea whats going on. Some entries don't have descriptions at all, just
leaves you scratching your head.

[mdipierro]

That is the problem.

for people who seriously want to help. Setting up another wiki is not
help. Instead, adopt a web2py file, add docstrings to all functions.

[Bruno Rocha]

Massimo, could you provide a list with reference to the files that need docs?
any way or idea, to separate, distribute the tasks, manage the
versions and make the moderation of docstrings.

I can help with that, a little every day, I reserve some hours of my
day for this task, it would be interesting even to me, so I learn more
about the framework, and it helps me to formulate training material
for my Python-Web2py classes, and to write the articles to the blog
and IT-Magazine that I mentioned to you by mail.

I agree with you, and I believe in future the documentation generated
in docstring could be shifted toward an easy reference guide.

Furthermore, I advocate using a help forum (PyForum), instead of
concentrating everything in the group,I like most of the style of
organizing a forum, I'm pretty used to seek help in ubuntuforuns and
several others, IMHO Forum has much more effective role in providing
help than a list like this, forum is easy to search, best indexed by
search engines, best with usability, navigation etc.

How can we start with docstrings?

2010/7/13 mdipierro <mdip...@cs.depaul.edu>:

--

http://rochacbruno.com.br

[mdipierro]

I would look into the most common files

globals.py
html.py
sql.py

only stuff defined in these files is exposed to users. The rest is all
internals.

On 13 Lug, 17:31, Bruno Rocha <rochacbr...@gmail.com> wrote:
> Massimo, could you provide a list with reference to the files that need docs?
> any way or idea, to separate, distribute the tasks, manage the
> versions and make the moderation of docstrings.
>
> I can help with that, a little every day, I reserve some hours of my
> day for this task, it would be interesting even to me, so I learn more
> about the framework, and it helps me to formulate training material
> for my Python-Web2py classes, and to write the articles to the blog
> and IT-Magazine that I mentioned to you by mail.
>
> I agree with you, and I believe in future the documentation generated
> in docstring could be shifted toward an easy reference guide.
>
> Furthermore, I advocate using a help forum (PyForum), instead of
> concentrating everything in the group,I like most of the style of
> organizing a forum, I'm pretty used to seek help in ubuntuforuns and
> several others, IMHO Forum has much more effective role in providing
> help than a list like this, forum is easy to search, best indexed by
> search engines, best with usability, navigation etc.
>
> How can we start with docstrings?
>

> 2010/7/13 mdipierro <mdipie...@cs.depaul.edu>:

[weheh]

Massimo, isn't epydocs more geared to the web2py developer than the
user? I agree, embedding the user documentation into the code is
desireable (write once, serve many). But, users and developers have
differing needs and comprehension levels. If the output of epydocs can
be optimized to also support reading by a web2py user through a
combination of information filtering, document formatting conventions
and templates, and user comments, then I'm all in favor of it as it
will likely save time and effort.

[mdipierro]

It depends. If the docstrings are well written they can be useful to
both.

[weheh]

Then, let it be epydocs (thanks ra3don). Let's get concensus on a good
template for a man-page docstring and get on with it!

I'm going to suggest that major headings include:

Name of command
Synopsys
Description
Parameters and their meanings
Return values
Examples
Links (to external documentation)
Comments

I just now looked at the php documentation and it covers all the
above. Indeed, it looks really useful and is well organized.

[mdipierro]

We had an attempt to use rest and sphinx but now that despitce help
form many people we never managed to make it work decently because of
third party dependencies. I'd rather use something that only requires
web2py to be parsed. MARKMIN was designed in such a way to allow this

def example():
"""
# title [[example]]
this is a doc string and the following is a doctest

``
>>> print 'hello world'
hello world
``:code_python

Read more: [click here #example]]
"""

Notice a docstring that contains a doctest which is also a markmin
code that specifies the language for highlight, an [[anchor]] and a
[[link the #anchor]]. And no weird :: like in rest.

[weheh]

Massimo, again, I'm all in favor of simplicity, especially if it means
less of your time involved. The convention for a man page and the
markup language need to be documented as the first step in making the
reference, and preferably, should be a part of the reference
itself.Obviously, this forum is not the ultimate resting place for
this info. How and where would that be entered into the epydocs if
that's not a python function, per se?

[Christopher Steel]

Markmin looks pretty sweet, tiny and fast!

http://www.web2py.com/examples/static/markmin.html

C.