Re: [Zope-dev] Re: new zope.org, sphinx, and documentation management
Hi Paul. For what it's worth, here's what I am doing which seems to work without a new recipe at this point. The rest should be just the overrides for the templates I believe but not what else you are doing with your docs. 1. Create a docs/html folder in my buildout 2. Add the following sphinx part 3. run ./bin/sphinx-quickstart (use all the defaults - no make file though) 4. run ./bin/sphinx-build -b html -d .build/doctrees . docs/html Regards, David [buildout] versions = versions parts = sphinx log-level = DEBUG [versions] Sphinx = 0.1.61950 Pygments = 0.9 [sphinx] recipe = zc.recipe.egg scripts = sphinx-quickstart sphinx-web sphinx-build eggs = Sphinx docutils Pygments David Pratt wrote: Hey Paul. It's definitely something I want, so will examining this further and let you know if I come up with something. Regards, David Paul Carduner wrote: On Fri, Apr 25, 2008 at 5:48 AM, David Pratt <[EMAIL PROTECTED]> wrote: Hi Paul. Good work. Personally, I am interested in switching out the jinja templates for zpt or ctal since am not that keen about mixing template languages for myself. It looks like the more recent changes to sphinx should accommodate this with the template_bridge but have yet to investigate this further. I agree with you that using zpt would be more preferable. At this point though I don't think we have an immediate need for it. The only change I made to the sphinx default template was adding some static html for the zope branding. Eventually though, if we want to build a more robust documentation build tool with direct zope integration, zpt would be absolutely necessary. But if you are volunteering to research using the template bridge, I'd be happy to use whatever you come up with. - Paul -- Paul Carduner http://www.carduner.net ___ Zope-Dev maillist - Zope-Dev@zope.org http://mail.zope.org/mailman/listinfo/zope-dev ** No cross posts or HTML encoding! ** (Related lists - http://mail.zope.org/mailman/listinfo/zope-announce http://mail.zope.org/mailman/listinfo/zope ) ___ Zope-Dev maillist - Zope-Dev@zope.org http://mail.zope.org/mailman/listinfo/zope-dev ** No cross posts or HTML encoding! ** (Related lists - http://mail.zope.org/mailman/listinfo/zope-announce http://mail.zope.org/mailman/listinfo/zope )
Re: [Zope-dev] Re: new zope.org, sphinx, and documentation management
Hey Paul. It's definitely something I want, so will examining this further and let you know if I come up with something. Regards, David Paul Carduner wrote: On Fri, Apr 25, 2008 at 5:48 AM, David Pratt <[EMAIL PROTECTED]> wrote: Hi Paul. Good work. Personally, I am interested in switching out the jinja templates for zpt or ctal since am not that keen about mixing template languages for myself. It looks like the more recent changes to sphinx should accommodate this with the template_bridge but have yet to investigate this further. I agree with you that using zpt would be more preferable. At this point though I don't think we have an immediate need for it. The only change I made to the sphinx default template was adding some static html for the zope branding. Eventually though, if we want to build a more robust documentation build tool with direct zope integration, zpt would be absolutely necessary. But if you are volunteering to research using the template bridge, I'd be happy to use whatever you come up with. - Paul -- Paul Carduner http://www.carduner.net ___ Zope-Dev maillist - Zope-Dev@zope.org http://mail.zope.org/mailman/listinfo/zope-dev ** No cross posts or HTML encoding! ** (Related lists - http://mail.zope.org/mailman/listinfo/zope-announce http://mail.zope.org/mailman/listinfo/zope )
Re: [Zope-dev] Re: new zope.org, sphinx, and documentation management
On Fri, Apr 25, 2008 at 5:48 AM, David Pratt <[EMAIL PROTECTED]> wrote: > Hi Paul. Good work. Personally, I am interested in switching out the jinja > templates for zpt or ctal since am not that keen about mixing template > languages for myself. It looks like the more recent changes to sphinx should > accommodate this with the template_bridge but have yet to investigate this > further. I agree with you that using zpt would be more preferable. At this point though I don't think we have an immediate need for it. The only change I made to the sphinx default template was adding some static html for the zope branding. Eventually though, if we want to build a more robust documentation build tool with direct zope integration, zpt would be absolutely necessary. But if you are volunteering to research using the template bridge, I'd be happy to use whatever you come up with. - Paul -- Paul Carduner http://www.carduner.net ___ Zope-Dev maillist - Zope-Dev@zope.org http://mail.zope.org/mailman/listinfo/zope-dev ** No cross posts or HTML encoding! ** (Related lists - http://mail.zope.org/mailman/listinfo/zope-announce http://mail.zope.org/mailman/listinfo/zope )
Re: [Zope-dev] Re: new zope.org, sphinx, and documentation management
Hi Paul. Good work. Personally, I am interested in switching out the jinja templates for zpt or ctal since am not that keen about mixing template languages for myself. It looks like the more recent changes to sphinx should accommodate this with the template_bridge but have yet to investigate this further. Regards, David Paul Carduner wrote: After a fair amount of work figuring out Sphinx, I modified the default css and template to produce something that could be more or less seemlessly integrated into the new zope.org. Anyhow, I encourage everyone to take a look at http://docs.carduner.net/z3c.form/ for a working example. This weekend I hope to make a buildout recipe that does all this in a more magical way. - Paul -- Paul Carduner http://www.carduner.net ___ Zope-Dev maillist - Zope-Dev@zope.org http://mail.zope.org/mailman/listinfo/zope-dev ** No cross posts or HTML encoding! ** (Related lists - http://mail.zope.org/mailman/listinfo/zope-announce http://mail.zope.org/mailman/listinfo/zope ) ___ Zope-Dev maillist - Zope-Dev@zope.org http://mail.zope.org/mailman/listinfo/zope-dev ** No cross posts or HTML encoding! ** (Related lists - http://mail.zope.org/mailman/listinfo/zope-announce http://mail.zope.org/mailman/listinfo/zope )
Re: [Zope-dev] Re: new zope.org, sphinx, and documentation management
After a fair amount of work figuring out Sphinx, I modified the default css and template to produce something that could be more or less seemlessly integrated into the new zope.org. Anyhow, I encourage everyone to take a look at http://docs.carduner.net/z3c.form/ for a working example. This weekend I hope to make a buildout recipe that does all this in a more magical way. - Paul -- Paul Carduner http://www.carduner.net ___ Zope-Dev maillist - Zope-Dev@zope.org http://mail.zope.org/mailman/listinfo/zope-dev ** No cross posts or HTML encoding! ** (Related lists - http://mail.zope.org/mailman/listinfo/zope-announce http://mail.zope.org/mailman/listinfo/zope )
Re: [Zope-dev] Re: new zope.org, sphinx, and documentation management
Hi Paul. This is beautiful. A recipe is what we need now. Send me a mail off list if you want some help with this. Regards, David Kent Tenney wrote: On Thu, Apr 24, 2008 at 2:09 AM, Paul Carduner <[EMAIL PROTECTED]> wrote: On Wed, Apr 23, 2008 at 10:48 PM, Paul Carduner <[EMAIL PROTECTED]> wrote: > On Wed, Apr 23, 2008 at 12:01 PM, Martin Aspeli <[EMAIL PROTECTED]> wrote: > I would start with the simple HTML approach, personally. It may be all we > > need. > > Hopefully there will be a first sample of this in the next hour or so. > Ok, I setup a sample of what sphinx produces after a quite minimal setup for z3c.form. Check it out at: http://docs.carduner.net/z3c.form/. I made a few small modifications to the existing documentation, which I checked into a branch on svn.zope.org along with the sphinx setup generated for me by the sphinx-quickstart command. A few goody features include: Full text searching powered by javascript: http://docs.carduner.net/z3c.form/search.html Module index with quick synopses: http://docs.carduner.net/z3c.form/modindex.html (click on the plus symbol after the big Z) Cross links to other parts of the documentation: http://docs.carduner.net/z3c.form/src/z3c/form/README.html So far, I think this is pretty good for what took me maybe an hour. Think of what it would be with some extra documentation cleanup. Cool!. The Zope-3.3.1 tree contains 70 README.txt, 309 *.txt so, more than 70 files of correct, up to the minute examples of use. That's a lotta doc. If not adequate in themselves, invaluable as link destinations when explaining with prose. As they grow ..contents:: directives, and more section headings are added, glossary tags are added, they will increase in value. -- Paul Carduner http://www.carduner.net ___ Zope-Dev maillist - Zope-Dev@zope.org http://mail.zope.org/mailman/listinfo/zope-dev ** No cross posts or HTML encoding! ** (Related lists - http://mail.zope.org/mailman/listinfo/zope-announce http://mail.zope.org/mailman/listinfo/zope ) ___ Zope-Dev maillist - Zope-Dev@zope.org http://mail.zope.org/mailman/listinfo/zope-dev ** No cross posts or HTML encoding! ** (Related lists - http://mail.zope.org/mailman/listinfo/zope-announce http://mail.zope.org/mailman/listinfo/zope ) ___ Zope-Dev maillist - Zope-Dev@zope.org http://mail.zope.org/mailman/listinfo/zope-dev ** No cross posts or HTML encoding! ** (Related lists - http://mail.zope.org/mailman/listinfo/zope-announce http://mail.zope.org/mailman/listinfo/zope )
Re: [Zope-dev] Re: new zope.org, sphinx, and documentation management
On Thu, Apr 24, 2008 at 2:09 AM, Paul Carduner <[EMAIL PROTECTED]> wrote: > On Wed, Apr 23, 2008 at 10:48 PM, Paul Carduner <[EMAIL PROTECTED]> wrote: > > On Wed, Apr 23, 2008 at 12:01 PM, Martin Aspeli <[EMAIL PROTECTED]> wrote: > > > > I would start with the simple HTML approach, personally. It may be all > > we > > > need. > > > > Hopefully there will be a first sample of this in the next hour or so. > > > > Ok, I setup a sample of what sphinx produces after a quite minimal > setup for z3c.form. Check it out at: > http://docs.carduner.net/z3c.form/. I made a few small modifications > to the existing documentation, which I checked into a branch on > svn.zope.org along with the sphinx setup generated for me by the > sphinx-quickstart command. A few goody features include: > > Full text searching powered by javascript: > http://docs.carduner.net/z3c.form/search.html > Module index with quick synopses: > http://docs.carduner.net/z3c.form/modindex.html (click on the plus > symbol after the big Z) > Cross links to other parts of the documentation: > http://docs.carduner.net/z3c.form/src/z3c/form/README.html > > So far, I think this is pretty good for what took me maybe an hour. > Think of what it would be with some extra documentation cleanup. Cool!. The Zope-3.3.1 tree contains 70 README.txt, 309 *.txt so, more than 70 files of correct, up to the minute examples of use. That's a lotta doc. If not adequate in themselves, invaluable as link destinations when explaining with prose. As they grow ..contents:: directives, and more section headings are added, glossary tags are added, they will increase in value. > > > > -- > Paul Carduner > http://www.carduner.net > ___ > Zope-Dev maillist - Zope-Dev@zope.org > http://mail.zope.org/mailman/listinfo/zope-dev > ** No cross posts or HTML encoding! ** > (Related lists - > http://mail.zope.org/mailman/listinfo/zope-announce > http://mail.zope.org/mailman/listinfo/zope ) > ___ Zope-Dev maillist - Zope-Dev@zope.org http://mail.zope.org/mailman/listinfo/zope-dev ** No cross posts or HTML encoding! ** (Related lists - http://mail.zope.org/mailman/listinfo/zope-announce http://mail.zope.org/mailman/listinfo/zope )
Re: [Zope-dev] Re: new zope.org, sphinx, and documentation management
On Wed, Apr 23, 2008 at 10:48 PM, Paul Carduner <[EMAIL PROTECTED]> wrote: > On Wed, Apr 23, 2008 at 12:01 PM, Martin Aspeli <[EMAIL PROTECTED]> wrote: > > I would start with the simple HTML approach, personally. It may be all we > > need. > > Hopefully there will be a first sample of this in the next hour or so. > Ok, I setup a sample of what sphinx produces after a quite minimal setup for z3c.form. Check it out at: http://docs.carduner.net/z3c.form/. I made a few small modifications to the existing documentation, which I checked into a branch on svn.zope.org along with the sphinx setup generated for me by the sphinx-quickstart command. A few goody features include: Full text searching powered by javascript: http://docs.carduner.net/z3c.form/search.html Module index with quick synopses: http://docs.carduner.net/z3c.form/modindex.html (click on the plus symbol after the big Z) Cross links to other parts of the documentation: http://docs.carduner.net/z3c.form/src/z3c/form/README.html So far, I think this is pretty good for what took me maybe an hour. Think of what it would be with some extra documentation cleanup. -- Paul Carduner http://www.carduner.net ___ Zope-Dev maillist - Zope-Dev@zope.org http://mail.zope.org/mailman/listinfo/zope-dev ** No cross posts or HTML encoding! ** (Related lists - http://mail.zope.org/mailman/listinfo/zope-announce http://mail.zope.org/mailman/listinfo/zope )
Re: [Zope-dev] Re: new zope.org, sphinx, and documentation management
On Wed, Apr 23, 2008 at 12:01 PM, Martin Aspeli <[EMAIL PROTECTED]> wrote: > Hi Paul, > > I've tried to sum up my understanding of how Zope 3 fits in with the Zope > universe here: > > http://zode01.lovelysystems.com/projects > > Beyond that, I think Zope 3 is becoming more and more a collection of > libraries and less of an application server. > Ok, I will add that to my list of bullets as something that someone out there thinks of zope. Thanks! > > Besides giving the 1 foot view of zope 3, there is also a section > > for zope 3 documentation on the new site, which should probably > > include detailed developer documentation along with tutorials, howtos, > > references, etc. Fortunately, a little known fact is that there is > > already a fair amount of up-to-date documentation about many zope3 > > packages in the form of doctests (some better written for end-user > > consumption than others). > > > > I think this is true, but doctests are only useful if you know where to > look and you have the required background. > > I would argue that we need more "prose-style" introduction/background > documentation. We probably also need a human-edited overview of the most > important Zope 3 packages. We can then point to doctests for more detailed > stuff. > I agree. Prose are good, with the one caveat that the new user coming to check out/download/install/play with zope (3) for 30 minutes, might not care to read a long story about the history of zope. I think such a history is important, but not as high a priority than just providing the information necessary to utilize the framework. Plus, I think it's possible that some of that prose-style instroduction/background could live with the code (not as a doctest, but just as a doc). > > Few people know about this because the > > documentation is not aggregated anywhere (except for some bits on > > apidoc.zope.org). You have to know to look on svn.zope.org or pypi > > pages to find the rest of it. Rather than writing a bunch of new > > documentation on the new zope.org site from scratch, I would like to > > harness the existing documentation, and just publish it in a nice way. > > > > Yep! > > Please note that we can enable the reST parser in Plone so that we can > paste reST into a document and have it render somewhat-nicely. That still > presumes some manual work though. > Big +1. I much prefer working on a reST document in emacs and copying and pasting into the plone site when I'm ready. That also allows me to save a nicely formatted local copy easily. Good for train rides with no internet. > > * THE POINT OF THIS EMAIL IS BELOW * > > > > I would like to develop a buildout recipe that generates aggregated > > documentation for a package (like z3c.form) using sphynx and publishes > > it to the new zope.org website. I want updating of zope documentation > > on zope.org to be as easy as uploading a package to pypi: > > > > Nice. :) > > I wonder if perhaps it would be easier to start with, to create a static > HTML site out of this documentation. If zope.org (as per > http://zode01.lovelysystems.com) is the "shop window" to Zope, then we can > focus on telling a compelling story there. We can have links to, say, > doc.zope.org (much like python.org does with doc.python.org), which can be > static HTML that's generated by this stuff. > Yep, my first goal is to learn more about sphinx and see what it can do. I'll probably be generating docs and sticking them on http://docs.carduner.net for the time being. > > When you are ready to make a release of a package, you would then do: > > $ cd z3c.form/tags/2.0/ > > $ python setup.py register sdist upload > > $ ./bin/buildout > > $ ./bin/update-documentation > > > > You would then be able to go to > > http://www.zope.org/projects/zope3/documentation/z3c.form and see > > everything from developer docs, to tutorials, to how-tos, etc. > > > > We could also write some code that pushes this into Plone over XML-RPC or > HTTP requests (or even zope.testbrowser...). This idea I like. That sounds like the way to do it. > Or: we could write some kind of Plone content type, parameterised with an > svn url, that pulled straight from svn and rendered doctests inline (this > means we wouldn't need a buildout recipe or sphinx, though we would need > some in-Plone caching and it'd be a bit of work to set up all the packages). This is probably overkill. > > What do people think of this idea and who wants to help me implement > > it this weekend? > > > > I would start with the simple HTML approach, personally. It may be all we > need. Hopefully there will be a first sample of this in the next hour or so. Thanks for your response! -- Paul Carduner http://www.carduner.net ___ Zope-Dev maillist - Zope-Dev@zope.org http://mail.zope.org/mailman/listinfo/zope-dev ** No cross posts or HTML encoding! ** (Related lists - http://mail.zope.org/mailman/
