Dear web2py-community,
after creating the Sphinx-based documentation
infrastructure for web2py I though:
Why not documenting also the applications?
You are all moving fast. I couldn't resist...
So with reference to my post [1], I present a modified
welcome application which has the following new
features:
1) A Sphinx template that can be used to document the
application. I think this a very convenient feature.
Imagine webdeveloper A creates an application of a
client but is not available any more after a few
months. With such a documentation the new
developer B can quickly take over!
2) An demonstration example for showing the docstrings
of an action on the frontend (i.e. in the view).
3) the database name has been changed:
databases/storage.db => databases/storage.sqlite
All nice but I need some help or experienced developer:
1) the way external modules are imported in web2py
makes it very difficult to use the sphinx extension
autodoc to autodocument the controller functions:
autodoc can' import/find module controllers.default
it reported error: No module named
applications.welcome_modif.modules.docutils please check your spelling
and sys.path
=> this happens because Sphinx uses the sys.path of
the systems Python install + the paths added in
conf.py whereas web2py seems to set its own
definitions. Possible solution are
* run sphinx from web2py admin
* correct the sys.path by some definitions in conf.py
=> I think the best would be if Massimo helps out here
I also added a VERSION file to about.html view which
is then read by Sphinx. The direcory name of the app
is used to derive the project name. But this may be
changed later. I first wanted to use the content of
ABOUT here, but this may be a very long string...
2) here I did not really know how to put a module in
web2py/modules which depend on each other:
web2py/modules/rest.py depends on
web2py/modules/docutils but when I insert
from docutils import core
from docutils.writers.html4css1 import Writer,HTMLTranslator
into the top of rest, I get a ImportError.
Anyway, I think that this this could be a good basis for
having well documented and efficient applications. This
functionality would generate even more momentum for
the framework as the applications become more
accessible.
This may even lead the way for an online editor for
Sphinx:
Just include the doc/source folder as another item in the
http://127.0.0.1:8000/admin/default/design
and provide edit acces to the RST files in that folder.
This would be not too difficult...
We need a voluteer here!
Please download, review, feedback or best merge into the main:
https://code.launchpad.net/~timmie/web2py/web2py-appdocu
Kind regards,
Timmie
Here is the changlog from the commit:
###
Updates and changes:
* a modified welcome app with documentation accessible through the admin
* python based makefile for app docs (also adapted admin default.py)
* admin about has new field for VERSION of the app which is used by
sphinx conf.py
* examples/docs.html: included link to Sphinx docs
* a missing file was added to web2py/docs/sources
(doc/source/docs_overview.rst)
* app docs linked from admin/site
* app docs are linked to Sphinx objects inv: see
http://127.0.0.1:8000/welcome_modif/static/doc_build/controllers.html
=> recommend you review with directroy based diff with a GUI diff tool!!!
Docs todo
* better integration of Sphinx build into web2py (backlink to admin
/examples)
* build docs for web2py & apps from admin
###
[1]: http://groups.google.com/group/web2py/msg/fc9579c68c931edb
From the
--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the Google Groups
"web2py Web Framework" group.
To post to this group, send email to [email protected]
To unsubscribe from this group, send email to
[email protected]
For more options, visit this group at
http://groups.google.com/group/web2py?hl=en
-~----------~----~----~----~------~----~------~--~---
