On Thu, Jun 5, 2008 at 8:51 AM, Kevin G. Baker <[EMAIL PROTECTED]> wrote:
> This is an interesting point. It might make sense to start a documentation
> standard. One that all these projects could embrace moving forward. If the
> docs were all in a standard format, like "man", they could be easily combined
> for projects like Pylons and other frameworks, sort of Legos for
> documentation. "Open Doc Blocks" ... ;)
>
> Something like this would help reduce redundancy, sort of normalization of
> docs, and might improve overall documentation support on a lot of projects
>
> Just a thought... does anyone know if there is any sort of standard like
> this? I tend to use Natural Docs for its easy skinning and support for it's
> multi-language and multi-doc syntax support. But this would only cover API
> docs...
>
> - Kevin Baker
Sphinx looks likely to become it. Both Pylons and Paste have switched
to it, as has Python's development versions. See:
http://docs.pylonshq.com/ (unfinished)
http://pythonpaste.org/
http://docs.python.org/dev/ (Python 2.6a3)
http://docs.python.org/dev/3.0/ (Python 3)
I haven't used Sphinx myself but I believe it combines ReStructured
Text articles into a book, and you can stick docstring-generated
content wherever you want. Ben has some plan to import the
documentation from Pylons' component projects into this scheme, but
I'm not sure exactly how it works. I imagine it's something like
svn:external for Sphinx content and a downloader-converter for
non-Sphinx content.
Pylons is doing this out of necessity because we need the
documentation. The Pylons docs themselves could theoretically be a
building block for some other documentation, but nobody has yet
outlined what that documentation might be. Perhaps a central
documentation repository in PyPI, or all web-related documentation at
docs.pythonweb.org.
A perennial problem with documentation is that building its structure
or tools takes time away from writing the content. That's why Pylons
went with Confluence originally for its wiki, because Confluence
provided a quick way to start writing without having to build
infrastructure).
Python for years used LaTeX with custom stylesheets. Other projects
like Cheetah followed suit. But LaTeX is a pain to maintain compared
to the newer HTML/DocBook/XML and ReST formats. But ReST didn't
support multi-article books very well (i.e., no standard way to make
next/previous/up links at the bottom of the page). Various programs
were written to fill this gap, but none emerged as pre-eminent so it
was a mess.
Pylons started using Pudge as a structure for application
documentation, but Pudge was difficult to install and buggy. Then
Sphinx came along and does it all better. I don't know how well it
handles multilingual docs; maybe somebody else can answer that.
--
Mike Orr <[EMAIL PROTECTED]>
--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the Google Groups
"pylons-discuss" group.
To post to this group, send email to [email protected]
To unsubscribe from this group, send email to [EMAIL PROTECTED]
For more options, visit this group at
http://groups.google.com/group/pylons-discuss?hl=en
-~----------~----~----~----~------~----~------~--~---
