Re: Docs docs docs!
2008/5/1 Graham Higgins [EMAIL PROTECTED]: (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, Probably. The docs were updated for 0.9.6, and Pylons hasn't changed that much since then. or whether there are any contributions in the cookbook that should be included.) There is certainly material in the Cookbook that deserves to be in the official docs. But whether we'll have time to go through the Cookbook and find it before the release is another question. It would take hours to read all the Cookbook articles and evaluate them. That's part of the Cookbook sweep I'm planning when development calms down. Find the gems, consolidate redundant articles, and delete obsolete material or move it to an old Pylons version section. The list of articles you made will help with that, though I expect I won't get to it till the end of May. If you know a few particular Cookbook articles that are especially worth putting in the official docs, that's a different issue of course. -- Mike Orr [EMAIL PROTECTED] --~--~-~--~~~---~--~~ You received this message because you are subscribed to the Google Groups pylons-devel group. To post to this group, send email to pylons-devel@googlegroups.com To unsubscribe from this group, send email to [EMAIL PROTECTED] For more options, visit this group at http://groups.google.com/group/pylons-devel?hl=en -~--~~~~--~~--~--~---
Re: Docs docs docs!
I've gotten the basic Sphinx setup working now, and have gotten the
Getting Started doc done. Here's what the Sphinx doc build looks like
so far:
http://docs.pylonshq.com/
I've got most of the module API docs laid out too. I should note that
this doc effort covers a few related packages as well, to update them
with Sphinx restructured text syntax (the previous pudge doc string
syntax breaks in a few places under Sphinx).
If you'd like to get started, here's the steps. First, I've put
together a single script that will create a virtualenv, install
Mercurial into it, grab all the source repo's for core Pylons packages
(pylons, beaker, weberror, webhelpers, routes), and do svn checkouts
of the other core packages (Paste, PasteScript, PasteDeploy, WebOb).
To run it, just use the following command:
curl http://pylonshq.com/download/0.9.7/go-pylons-dev.py | python - --
no-site-packages superdevenv
That will setup the whole thing underneath the directory
'superdevenv', this command does require svn to already be installed,
but doesn't require Mercurial to be installed as that's setup for you
in the directory you choose ('superdevenv' in this example).
To run the Sphinx build locally, first install Sphinx: ./superdevenv/
bin/easy_install -U Sphinx. Then go to superdevenv/pylons/pylons/docs
and type: make html
That should build the HTML source in a _build dir where you can then
browse it.
All the packages will also be setup in develop mode, so you can then
work on docs in various packages so we'll have powerful module API
docs for here:
http://docs.pylonshq.com/modindex.html
Which is helpful because we'll want to cross-link to them frequently
to avoid repetition in the actual docs.
So far, I've gotten some of the TOC filled in, and have setup
placeholders in sections with what I believe should be covered by that
section. I still need to add an Internationalization section as well.
If you'd like to help out, and/or have already stated that, just setup
a dev env like I mention here, find a section of the docs you'd like
to work on, and announce it here so we avoid working on the same
doc. :)Or we could just setup a page on the wiki to track who's
working on which sections.
Cheers,
Ben
smime.p7s
Description: S/MIME cryptographic signature
Re: Docs docs docs!
On Apr 9, 2008, at 6:08 AM, Graham Higgins wrote: I'd like to be involved Great to see you getting back into the docs! I'm assembling the first revision of the Pylons docs that will use Sphinx and be in the Pylons repo so that anyone installing Pylons will have a copy of the docs with them. However, before I can start yanking docs from the wiki that different people wrote, I need to know the license and copyright intention of those who wrote the docs. :) For the others that have expressed interest, I'll need a similar contribution license put together to ensure that I have appropriate rights for distribution of all contributed docs to Pylons as its messy to sort out copyright issues later. I was originally considering the GNU Free Documentation License (GFDL), but some of the criticism of its points seem rather valid, so I'm now looking at the BSD Documentation License as Pylons is entirely MIT licensed (which is essentially identical to the 2-clause BSD license). This is rather important as the GFDL actually has some odd issues when citing code that's covered by a different license from what I can tell. Repoze has a rather nice form put together here: http://repoze.org/contributing.html I'll modify as needed for those wishing to contribute to the Pylons core docs. That work for everyone? Cheers, Ben smime.p7s Description: S/MIME cryptographic signature
Re: Docs docs docs!
Ben Bangert wrote: I'd like to assemble a group of other people who are interested in working on the docs for Pylons. If you'd like to help work on the docs in any of these ways: Please let me know. I'd like to be involved. --~--~-~--~~~---~--~~ You received this message because you are subscribed to the Google Groups pylons-devel group. To post to this group, send email to pylons-devel@googlegroups.com To unsubscribe from this group, send email to [EMAIL PROTECTED] For more options, visit this group at http://groups.google.com/group/pylons-devel?hl=en -~--~~~~--~~--~--~---
Re: Docs docs docs!
On 3/24/08, Ben Bangert [EMAIL PROTECTED] wrote: I've been reading carefully through the docs for Sphinx ( http://sphinx.pocoo.org/ ) the past few days, and am quite sold on it at this point. As such, I'd like to assemble a group of other people who are interested in working on the docs for Pylons. Good news. I always thought Pylons docs seemed poor, esp. compared to Django. The parts in that list we'll be including in our docs is (and the approximate section in the Pylons docs): Pylons (Advanced Pylons) SQLAlchemy(Models - Working with Databases) Mako (Templating) Beaker (Sessions Caching) WebHelpers (Templating - Helpers) WebOb (Working with the Request/Response) FormEncode(Models - Validating user input) WebTest (Testing - web application testing) Nose (Testing - running the tests, writing them, etc) Paster (Advanced Pylons - WSGI, CLI scripts, etc) WebError (Testing/Debugging - troubleshooting) Babel(Internationalization) If you'd like to help work on the docs in any of these ways: - Write docs - Grammar / spelling checking - Copy editing (consistent usage of terms, tone of voice, etc.) - Technical review I'd like to help with #1 (write docs) and may be #4. I'm not a native English speaker so I'll refrain from #2,#3. As for package coverage, I'm interested in documenting Nose, Babel, WebOb. Though these packages have a better docs than the core Pylons (of course, they are much simpler conceptually as well). Max. --~--~-~--~~~---~--~~ You received this message because you are subscribed to the Google Groups pylons-devel group. To post to this group, send email to pylons-devel@googlegroups.com To unsubscribe from this group, send email to [EMAIL PROTECTED] For more options, visit this group at http://groups.google.com/group/pylons-devel?hl=en -~--~~~~--~~--~--~---
Re: Docs docs docs!
I can help out writing docs. I'll read up on this Sphinx thing today. K On Mar 23, 11:51 pm, Ben Bangert [EMAIL PROTECTED] wrote: If you'd like to help work on the docs in any of these ways: - Write docs - Grammar / spelling checking - Copy editing (consistent usage of terms, tone of voice, etc.) - Technical review Please let me know. I'll be putting together a rough outline and posting it shortly. Cheers, Ben --~--~-~--~~~---~--~~ You received this message because you are subscribed to the Google Groups pylons-devel group. To post to this group, send email to pylons-devel@googlegroups.com To unsubscribe from this group, send email to [EMAIL PROTECTED] For more options, visit this group at http://groups.google.com/group/pylons-devel?hl=en -~--~~~~--~~--~--~---
Re: Docs docs docs!
Hi, I'm new to pylons, I'm interested in Testing, WebOb and caching. I'm not native English speaker too. But maybe I can help the i18n part. Let me know if anything I can help. Kind regards, z. On Mon, Mar 24, 2008 at 2:51 PM, Ben Bangert [EMAIL PROTECTED] wrote: I've been reading carefully through the docs for Sphinx ( http://sphinx.pocoo.org/ ) the past few days, and am quite sold on it at this point. As such, I'd like to assemble a group of other people who are interested in working on the docs for Pylons. I should note that we'll actually be covering quite a bit more than what is in the Pylons package as this set of docs will cover all the major components used with Pylons, and users should only have to go to the website for a component for advanced usage. That is, there should be no need to be wandering off our docs unless you want to use a non- recommended component, or need advanced stuff (SQLAlchemy might be an exception of course). There is a page here of all the components used by both TurboGears2 and Pylons: http://wiki.pylonshq.com/display/pylonscookbook/Suggested+Improvements+to+the+Documentation The parts in that list we'll be including in our docs is (and the approximate section in the Pylons docs): Pylons (Advanced Pylons) SQLAlchemy(Models - Working with Databases) Mako (Templating) Beaker (Sessions Caching) WebHelpers (Templating - Helpers) WebOb (Working with the Request/Response) FormEncode(Models - Validating user input) WebTest (Testing - web application testing) Nose (Testing - running the tests, writing them, etc) Paster (Advanced Pylons - WSGI, CLI scripts, etc) WebError (Testing/Debugging - troubleshooting) Babel(Internationalization) If you'd like to help work on the docs in any of these ways: - Write docs - Grammar / spelling checking - Copy editing (consistent usage of terms, tone of voice, etc.) - Technical review Please let me know. I'll be putting together a rough outline and posting it shortly. Cheers, Ben --~--~-~--~~~---~--~~ You received this message because you are subscribed to the Google Groups pylons-devel group. To post to this group, send email to pylons-devel@googlegroups.com To unsubscribe from this group, send email to [EMAIL PROTECTED] For more options, visit this group at http://groups.google.com/group/pylons-devel?hl=en -~--~~~~--~~--~--~---
