[merge request] new restructured Sphinx doc into devel branch

[Tim Michelsen]

Hello,
I have issued a merge proposal. Please merge now to get as less
conflicts as possible.

I think thos subscribed have just received the message from LP.

I would like to add some small things:
* Contrary to what I wrote earlier today, I just did some more wrok on
this today. I did not want to leave the started work unfinshed. And
web2py moves incredibly fast...
* BUT, due to time constraints, I want to give this small contribution
in the hands of the web2py developers. I cannot work on this on
day-to-day basis like done in the last days.
* I included / incorporated the ideas exchanged with Yarko today on this
list.
* I hope this is a valuable contribution to the project.

All the best and keep up the nice work with web2py.

Kind regards,
Timmie

### Message of the merge proposal:

From the commit message:

This is a 2nd setup and push of the Sphinx doc branch based on devel
revision 750:
* FAQ now optional
* User Wiki now optional
* still 36 warnings caused by the docstrings
* the intro docs have been corrected and are free of errors and warnings
Please provide feedback on the web2py mailing list
The branch will be proposed for a merge with the devel branch.

Reasons for this merge proposal:
* current web2py/doc contains many errors
* this branch provides a neat basis for further development of the
Sphinx doc
* this branch enables developers to test and improve docstrings
* now after the commit of 750 a merge will be painless

[mdipierro]

Thank you Tim. I will do it tomorrow morning.

[mdipierro]

I replaced the old doc folder with the new doc folder from your
branch.
I did not see any other difference. Is that correct?

Massimo

[Timmie]

* I added 3 rules to .bzrignore
* the build is placed in the direcory you specified if the make-
doc_html.xxx is used.

No other differences outsite the doc subdirecory.

[Zoom.Quiet]

great! i waiting new include Sphinx API doc branch,
so i'll creat Chinese version branch base this...

--
http://zoomquiet.org
'''过程改进乃是催生可促生靠谱的人的组织!'''
PE keeps evolving organizations which promoting people be good!

[mdipierro]

I really want must commend Tim and Yarko for their work on Sphinx.
This is the best thing that happened to web2py. We still have a long
way to go because we need to make all docstrings reST compliant.

It would help
1) somebody could post a very short howoto
2) everybody could contribute by picking a file in gluon/* and editing
the docstrings.

We can get this done in one week!

Massimo

On May 6, 5:57 pm, Tim Michelsen <timmichel...@gmx-topmail.de> wrote:

[Yarko Tymciurak]

I will work on howto tonight -

at least these 3 levels (and examples):

-- for functions;

-- for classes;

-- for inline additional docstrings (?)

[Yarko Tymciurak]

I must ammend - I've talked about sphinx, pushed for it, for reST wiki, etc.

This checkin is _all_ the efforts of Tim (I just reviewed, looked, commented).

Thanks _so much_, Tim!

With gratitude,

Yarko

On Thu, May 7, 2009 at 11:06 AM, mdipierro <mdip...@cs.depaul.edu> wrote:

[Tim Michelsen]

> I will work on howto tonight -

Just start off here:
http://bazaar.launchpad.net/~mdipierro/web2py/devel/annotate/head%3A/doc/source/docs_contrib.rst

[Tim Michelsen]

> Thanks _so much_, Tim!
I am delighted that you like.
Was some "hand"-work on top. But I think better now than later when
there will be more docstrings....

BTW,
Each app could have its own doc folder...

At least mine has one!

[mdipierro]

could you elaborate?

[Tim Michelsen]

>> BTW,
>> Each app could have its own doc folder...
>
> could you elaborate?

1) create a doc folder in the app folder
2) cd doc
3) $: sphinx-quickstart
4) write some intraductory text
5) include docstrings complying with web2py howto (to be written)
6) create a document that uses autodoc to API document the controllers,
models.
6) built the docs.

There could be a example for the examples application.
And a template created when a new application is created in the admin.
If you want, you can also use admin to modify basic values of Sphinx
config.py.

Can you see where I am looking at?

Please remind me to post the front end auto-documenting app. I do not
have time today, but...

Regards,
Timmie

[Yarko Tymciurak]

Thanks Tim - I will make more specific, with template examples especially so people can quickly contribute / update the gluon files - the "in one week" project.

Tonight I want to make that really easy to do consistently (grab a template, copy what's aready in a docstring, "reST"-ify it per template, and add / expand whatever missing sections you can, e.g. add examples)

[Yarko Tymciurak]

On Thu, May 7, 2009 at 2:41 PM, Tim Michelsen <timmic...@gmx-topmail.de> wrote:

>> BTW,
>> Each app could have its own doc folder...
>
> could you elaborate?

1) create a doc folder in the app folder

We could make this part of standard template, part of welcome app (first gluon gocstrings!)

2) cd doc
3) $: sphinx-quickstart

would already be there w/ template (as Tim says, below)

4) write some intraductory text
5) include docstrings complying with web2py howto (to be written)
6) create a document that uses autodoc to API document the controllers,
models.
6) built the docs.

We could even add to admin a "build docs" link - and check for presence of sphinx, docutils

This would encourage all apps to have at least basic docs.
Also, for apps for end users, we'd want to have / make build of docstrings separate from end user docs (so you could choose which to give to your end users as part of your app).

We can also (eventually) get fancy and include an overview directory with links to the TOC, and short description of each app in a web2py installation...

But this would be building on what we are starting w/ Tim's effort, and now w/ docstrings updates over the next week.

- Yarko