On May 1, 2008, at 5:33 AM, Graham Higgins wrote:
gettingstarted configuration controllers templates helpers models testing debugging deploymentI've been playing with a candidate structure which attempt to integrate some of the pre-existing documentation. (Ben, it's not clear whether you intend to "Re-do from start" or to integrate the pre-existing pylonsdocs material in confluence where it is relevant to the new structure, or whether there are any contributions in the cookbook that should be included.)
I did quite a bit of revamping when moving the Getting Started over. Mainly, I'm focused on a few things during the move which prevented me from just dumping entire docs in: - Being concise. A lot of the existing docs have a lot of additional wording that doesn't actually help explain it (or explains other things inadequately that will actually be explained in full somewhere else). - Adding Sphinx cross-linking, marking up words that have definitions. This helps with the goal of being concise, by limiting how often one has to repeat themselves. The Getting Started shrunk quite a bit thanks to the cross-referencing capability.
As such, it's not quite redoing from start, but it is quite a bit more than just dumping existing docs in. Especially since I'd like to use the structure shown.
I think that quite a few docs from the cookbook should go in, especially entire sections of the "in a hurry" docs. Ie, the Routes in a Hurry could definitely be the starting base for URL Configuration in the Configuration section. Some of the other sections of Configuration have never actually been documented, and while there's sections from the cookbook and such covering the REST controller, etc. There's no actual explanation of the WSGIController, how a Controller should work, what should go into it, etc. I don't think such an explanation in our concise docs will be that long, probably only a few paragraphs with a quick sample. At which point I think moving the other sections in as you show below will work great.
.. toctree:: :maxdepth: 2 Getting Started <gettingstarted> Models <models/models> Models - Working with Databases† <models/sqlalchemy> Models - Validating user input† <models/formencode> Controllers <controllers/controllers> Controllers - using the REST Controller for a RESTful API <controllers/rest_controller> Controllers - using the WSGI Controller for WSGI services <controllers/wsgi_controller> Controllers - using the XMLRPC controller for XML-RPC requests <controllers/xmlrpc_controller> Templating <templates/templates> Templating - Mako† <templates/mako> Templating - Helpers† <templates/webhelpers> Internationalization and localization <i18n/i18n> Internationalization - using Babel† <i18n/babel> Sessions & Caching† <beaker> Helpers <helpers> Working with the Request/Response† <webob> Testing <testing/testing> Testing - web application testing† <testing/webtest> Testing - running and writing tests† <testing/nose> Debugging <testing/debugging> Testing/Debugging - troubleshooting† <testing/weberror> Deployment <deployment> Python 2.3 Installation Instructions <python23_install> Windows Notes <windowsnotes> Configuration <configuration>
Configuration is actually pretty important, it should be kept at the top right after getting started. This is because how the app is setup is fairly critical in a lot of ways, especially in seeing the URL configuration.
I should note that after moving and updating the docs as I mentioned, we will likely need to go through them one or two more times, since we'll be able to make them more concise since we're able to cross-link heavily.
Advanced Pylons† <advanced_pylons/advanced_pylons> Advanced Pylons - WSGI, CLI scripts, etc† <advanced_pylons/paster>
The WSGI bit won't be needed, this will be explained somewhat in the Configuration of the middleware, and we'll have some more docs on WSGI elsewhere. People looking for an advanced in depth Pylons should get the book, its out of our scope here.
Third Party-Routes-Base <thirdparty/routes_base> Third Party-Util <thirdparty/routes_util> Third Party-WebOb <thirdparty/webob>
There'll be a few more for other Pylons stuff, like Beaker, FormEncode, etc. I should note that these sections are essentially module docs blocks in Sphinx, which let us pull in module docs for the third party module, but then add our own documentation mixed in. This way we can document how the module works with Pylons in addition to highlighting the critical parts as they'll be used in Pylons. We also won't need to duplicate docs since Sphinx can pull in the doc strings from the other package when applicable.
Hopefully that helps explain the methodology I'm applying somewhat? I'd highly suggest at least skimming the Sphinx docs, and especially how the autodoc extension works.
Cheers, Ben
smime.p7s
Description: S/MIME cryptographic signature
