> 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/
These are basically unfinished too, but I figured it was better than how it used to be anyway. > 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. You just tell Sphinx to put an object's docstring in a particular location, and it does it. So as long as the other packages are installed you can insert their docstrings in. > 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. There has been some discussion about a closer relationship between "these" projects (mostly Pylons, Paste, TG, and Repoze), and having a cohesive documentation story is a big part of that. We don't have any actual plans yet, though, just intentions. > 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). I find Sphinx fairly workable. At least personally I really prefer to write docs in text files under version control, which is what Sphinx is built for. I think Sphinx's emphasis on hand-crafted documentation is probably best. > 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. I don't think it has any special support. I'm not sure what that support would look like, but it's under active development and if someone can suggest something it might happen. People have implemented automatic Google translation links, and I guess they are okay at being readable, though no one was able to figure out a way to protect the code samples from translation. It would be spiffy if we could do automatic translation with hints when the translation goes wrong, so as to reduce the translation overhead. E.g., I could imagine a custom translation dictionary as ambiguous words are probably not very ambiguous in the context of our documentation (e.g., "code" almost always means "source code" not "cipher"). I don't know if there's translation services with a complete enough API for that sort of thing...? The public translation services seem pretty much all-or-nothing. But maybe translation with fixup? E.g., translate everything, then re-insert code samples over the translated code samples. And find phrases that are wrong and do a search-and-replace on those phrases. If you save the search-and-replace commands (as submitted by readers/translators) instead of saving the resulting text, they could be reapplied to the documentation after it is rebuilt, when the upstream documentation has changed. Obviously not perfect, but seems a whole lot easier to maintain than other translation strategies. Especially when completeness and accuracy is more important than expressiveness -- if you aren't sure the translated docs are completely right and complete, you'd be well served to read the original docs even if that's harder for you to do. (I think this is where translation of programming documentation is probably different than many other typical translation situations, where you might be more reluctant to deal with an obviously inferior automatically translated document.) -- Ian Bicking : [EMAIL PROTECTED] : http://blog.ianbicking.org --~--~---------~--~----~------------~-------~--~----~ 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 -~----------~----~----~----~------~----~------~--~---
