new zope.org, sphinx, and documentation management
Hi All, <lots of small talk follows, scroll down to **** section for the main point of this email> I guess I have officially volunteered to write content for the new zope.org site in the zope 3 section. Part of that involves describing what zope 3 is in a concise manner. I realize there are probably a lot of different opinions about what zope 3 is, so I would like to solicit the community to provide me with some ideas of what zope 3 is to you. It doesn't have to be anything fancy or publishable, just a bulleted list of "what zope 3 means to me" would be fine. I will aggregate these ideas and try to present it in an easy to read form. I don't want to start any arguments about what zope 3, so let's wait until I have something written before we start arguing :). Besides giving the 10000 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). 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. To this end I have taken a look at sphinx, the new documentation publishing tool used by python.org. In short, it looks really good, and I think we could use it for zope documentation. Here is my thinking: Keeping *lots* of documentation maintained in any CMS or wiki style website is hard, because the people writing the code want to maintain everything (including documentation) in one place: subversion. It is too much to ask every developer to update a website every time they make a change to the codebase, because the website lives in firefox, while the code lives in vim or emacs. But if the documentation lives with the code, updating the documentation can become part of the normal flow of writing software (just like writing tests is part of the normal flow). So ideally, all package specific documentation *including tutorials and other end user docs* should live along side the code in subversion. Now the trick is just publishing this documentation. ***** 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: 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. What do people think of this idea and who wants to help me implement it this weekend? -- Paul Carduner http://www.carduner.net
Hi Paul,
I guess I have officially volunteered to write content for the new zope.org site in the zope 3 section. Part of that involves describing what zope 3 is in a concise manner. I realize there are probably a lot of different opinions about what zope 3 is, so I would like to solicit the community to provide me with some ideas of what zope 3 is to you. It doesn't have to be anything fancy or publishable, just a bulleted list of "what zope 3 means to me" would be fine. I will aggregate these ideas and try to present it in an easy to read form. I don't want to start any arguments about what zope 3, so let's wait until I have something written before we start arguing :).
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.
Besides giving the 10000 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.
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.
To this end I have taken a look at sphinx, the new documentation publishing tool used by python.org. In short, it looks really good, and I think we could use it for zope documentation. Here is my thinking:
Cool!
Keeping *lots* of documentation maintained in any CMS or wiki style website is hard, because the people writing the code want to maintain everything (including documentation) in one place: subversion. It is too much to ask every developer to update a website every time they make a change to the codebase, because the website lives in firefox, while the code lives in vim or emacs. But if the documentation lives with the code, updating the documentation can become part of the normal flow of writing software (just like writing tests is part of the normal flow). So ideally, all package specific documentation *including tutorials and other end user docs* should live along side the code in subversion. Now the trick is just publishing this documentation.
I agree with this assessment.
***** 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.
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...). 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).
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. Martin -- Author of `Professional Plone Development`, a book for developers who want to work with Plone. See http://martinaspeli.net/plone-book
On Wed, Apr 23, 2008 at 12:01 PM, Martin Aspeli <optilude@gmx.net> 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 10000 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
On Wed, Apr 23, 2008 at 10:48 PM, Paul Carduner <paulcarduner@gmail.com> wrote:
On Wed, Apr 23, 2008 at 12:01 PM, Martin Aspeli <optilude@gmx.net> 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
On Thu, Apr 24, 2008 at 2:09 AM, Paul Carduner <paulcarduner@gmail.com> wrote:
On Wed, Apr 23, 2008 at 10:48 PM, Paul Carduner <paulcarduner@gmail.com> wrote:
On Wed, Apr 23, 2008 at 12:01 PM, Martin Aspeli <optilude@gmx.net> 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 )
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 <paulcarduner@gmail.com> wrote:
On Wed, Apr 23, 2008 at 10:48 PM, Paul Carduner <paulcarduner@gmail.com> wrote:
On Wed, Apr 23, 2008 at 12:01 PM, Martin Aspeli <optilude@gmx.net> 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 )
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
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 )
On Fri, Apr 25, 2008 at 5:48 AM, David Pratt <fairwinds@eastlink.ca> 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
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 <fairwinds@eastlink.ca> 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
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 <fairwinds@eastlink.ca> 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 )
Paul Carduner a écrit :
***** 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:
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.
Won't it be redundant with the doctests displayed on the PyPI? You speak about things like z3c.form, i.e. individual packages. They already have their doc (readme) displayed on the cheeseshop, which is the first place to look for packages. The problem is that many README.txt are more unittests than high level docs. In my opinion many README.txt contents should be moved into deeper functional doctests, and replaced by real introductions, or easy-to-read howtos. On zope.org, instead of individual egg docs, we need high level docs or integration docs that cover several packages at once. In which eggs do you want to put them? Christophe
On Wed, Apr 23, 2008 at 09:44:45PM +0200, Christophe Combelles wrote:
Paul Carduner a écrit :
***** 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: 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.
Won't it be redundant with the doctests displayed on the PyPI? You speak about things like z3c.form, i.e. individual packages. They already have their doc (readme) displayed on the cheeseshop, which is the first place to look for packages. The problem is that many README.txt are more unittests than high level docs. In my opinion many README.txt contents should be moved into deeper functional doctests, and replaced by real introductions, or easy-to-read howtos.
+1 for strict separation of API docs from tests.
On zope.org, instead of individual egg docs, we need high level docs or integration docs that cover several packages at once. In which eggs do you want to put them?
Marius Gedminas -- * philiKON wonders what niemeyer is committing :) *** benji_york is now known as benji <benji> murder? -- #zope3-dev
On Wed, Apr 23, 2008 at 2:44 PM, Christophe Combelles <ccomb@free.fr> wrote:
Paul Carduner a écrit :
***** 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:
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.
Won't it be redundant with the doctests displayed on the PyPI?
Sphinx provides added value to existing doc. The PyPi page is fine, but it's nice to have a front page with searching, indexing, TOC, which is all basically free. The page which exposes the doctests would explain the heritage of this material. Some will prefer it to doc written from scratch. The beauty of the existing doctest is that it is maintained and correct. It would be nice if there could be a level of commit permission just for enhancing the doctests for Sphinx. see http://sphinx.pocoo.org/markup/index.html
You speak about things like z3c.form, i.e. individual packages. They already have their doc (readme) displayed on the cheeseshop, which is the first place to look for packages. The problem is that many README.txt are more unittests than high level docs. In my opinion many README.txt contents should be moved into deeper functional doctests, and replaced by real introductions, or easy-to-read howtos.
On zope.org, instead of individual egg docs, we need high level docs or integration docs that cover several packages at once. In which eggs do you want to put them?
Christophe
_______________________________________________ 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 )
On Wed, Apr 23, 2008 at 12:44 PM, Christophe Combelles <ccomb@free.fr> wrote:
Paul Carduner a écrit :
***** 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:
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.
Won't it be redundant with the doctests displayed on the PyPI? You speak about things like z3c.form, i.e. individual packages. They already have their doc (readme) displayed on the cheeseshop, which is the first place to look for packages.
The problem is that the cheeseshop produces one page for *all* the documentation you upload to it. This is really not ideal for more than a simple introduction. The zopeproject page (or the zcontact page) on pypi are good examples where pypi is a nice starting point. But for more extensive documentation, pypi just isn't going to cut it. It would be interesting if sphinx were one day integrated into pypi, but I doubt that will happen in the near future.
The problem is that many README.txt are more unittests than high level docs. In my opinion many README.txt contents should be moved into deeper functional doctests, and replaced by real introductions, or easy-to-read howtos.
I agree. Part of the work involved in utilizing doctests for documentation would be editing the existing doctests themselves to make them more readable and end user consumable, and refactoring low-level doctests to deeper levels that are more test than doc, and not having them appear as part of the greater documentation at all.
On zope.org, instead of individual egg docs, we need high level docs or integration docs that cover several packages at once. In which eggs do you want to put them?
I would argue that integration docs should be in the form of a tutorial or demo. Take for example z3c.formdemo. This integrates quite a number of different packages and would be a great place for "integration documentation". Basically, integration docs would have their own package in svn.zope.org, in the form of an executable demo plus lots of great documentation. -- Paul Carduner http://www.carduner.net
Paul Carduner wrote:
consumption than others). Few people know about this because the documentation is not aggregated anywhere (except for some bits on apidoc.zope.org).
Not so! I recently did this at http://wiki.zope.org/zope3 . I hope it helps you.
participants (7)
-
Christophe Combelles -
David Pratt -
Kent Tenney -
Marius Gedminas -
Martin Aspeli -
Paul Carduner -
Simon Michael