Great work Tim. It will take some time to digest it.
On May 11, 3:50 pm, Tim Michelsen <[email protected]> wrote:
> 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
> thehttp://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:
> seehttp://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
-~----------~----~----~----~------~----~------~--~---
