[Twisted-web] documentation -- Techno Turkey's fifth adventure

[lloyd at paisite.com]

Hi Folks,

Sounds like I kicked off a vital and worthy discussion with my
questions/request re: development environment. Very exciting!

My instincts tell me that it'w worth letting this discussion run it's
course for another couple of days until we arrive at a consensual
plan-of-attack. Best I can contribute is a summery of suggestions to date:

Development Environment:

-- Valentino suggests we take a look at:

> An alternative for Nevow is using Combinator (explained in the Divmod
> Combinator page): http://divmod.org/trac/wiki/DivmodCombinator
> Another alternative for Nevow is using setuptools although I'm unsure how
> working itis. Yet another for both is using .pth


Twisted Coding Standards

-- Valentino also suggests we review:

> http://twistedmatrix.com/projects/core/documentation/howto/policy/coding-standard.html

-- glyph suggests:

There is actually an under-maintained Axiomatic plugin in Mantissa which
helps with this somewhat; it probably doesn't work at the moment, but
check out "axiomatic mantissa".  It might help with this kind of setup, or
at least provide some ideas for tools to expedite the turkey's adventures.


Directory Structure

-- Daniel says:

> While you are correct that no specific directory layout conventions have
> been blessed by the core development team, I think that there is a lot of
> value in  providing one, if only to give really new users some kind of
> structural anchor point from which to begin learning web-app development
> with twisted.

(Speaking for the turkey contingent, I heartily agree.)

-- Daniel suggests:

/ProjectName
   /packagename
     /static
       /css
       /js
       /images
     module1.py
     module2.py
     ...

-- Valentino counters:

/ProjectName
   /static
       /i   - images
       /s   - styles
       /j   - javascript
   /template
   /doc
   /database - sql files
   /bin      - various scripts
   /projectname - python modules
       /web  - for the web stuff
       /storage - for the data layer
       /other_eventual_twisted_using_subparts
      common_python_modules.py

-- Manlio asks:

> An interesting question is: when one should consider the option of serving
>  static content with a server like lighttpd, and forward with mod_proxy
> requests for dynamic content to twisted web?

> static.File is a no match versus lighttpd, but there is the overhead of
> mod_proxy and one should also consider how to design the site layout at
> the best.

.pth vs. PATH

-- Daniel says:

> I suggest using .pth files rather than path variables.  Using .pth files
> should "just work" regardless of your OS, and not require any fiddling
> around with the environment by hand.

> So, basically, for a new web project, you'd create your project dirs, and
> then stick a "myproject.pth" file in the site-packages directory,
> containing "/path/to/my/project/topmost/folder"

Testing development environment

> To test that the dev environment is set up correctly, I'd just start up a
> python interpreter prompt and import twisted, then import nevow, and
> lastly, import myprojectpackage.

Running Twisted code

-- Daniel suggests:

> I probably sound like a broken record, but I'd suggest offering one, and
> only one, way to run the code, so that users aren't fiddling with things
> that are not central to grasping the concepts being presented.

> Me, I use .tac files for everything these days, so that's what I would
> recommend for use within the tutorials.

Seems to me that these are all open questions worth consideration and
further discussion and clarification. As soon as we have some degree of
mutual understanding and concensus, we can discuss how to implement the
Turkey's Guide for Diving into Twisted or whatever we decide to call it,
as well as where to put it.

Meanwhile...

I'll post the next draft of Dialtone's Resource Magic on
http://twisted.paisite.com, incorporating suggested changes.

Many many thanks to all.

Best wishes,

Lloyd