osimons wrote: > On May 14, 2:29 pm, "Alec Thomas" <[EMAIL PROTECTED]> wrote: > >> 2008/5/14 Noah Kantrowitz <[EMAIL PROTECTED]>: >> >> >>> What would people think about basing our new docs around the Sphinx system >>> (http://sphinx.pocoo.org/)?It seems to provide a number of nice support >>> functions beyond simply putting each doc in a file and running rst2html or >>> something. The pickle builder would be a good starting place for the >>> integration with osimmion's newhelp interface (I think). This would mean >>> Sphinx and Pygments would be required for building the documentation (and >>> therefore for building release media), but neither would be runtime >>> dependencies. Thoughts? >>> >> I've been converting the documentation for my own applications to >> Sphinx, and it's been a very pleasant experience. As a bonus, I think >> it would also save us a lot of work. >> >> > > Sphinx appeared just after getting draft 1 of the newhelp branch > ready, and I agree that it does look promising. I say that having just > browsed the front page and some minimal docs, and have no real clue or > idea as to how to do this yet. I would need to actually install and > play with it, which I just have not found time to do yet. Nor has it > been a high priority issue for me to make 'ring-bound' documentation - > my main motivation was moving the pages out of the wikis of each > project, and rendering them using available Trac mimeviewers depending > on format - which is all Trac wiki for the time being. > > With the plugin architecture for providing help pages + being format > agnostic, 'newhelp' tries to make it effortless for others to provide > documentation as an ever-increasing part of Trac is provided by > plugins. And, add to this the i18n issues of providing some/all the > pages localized... > > Sphinx looks interesting and I will look into it at some stage, but > I'm mostly wondering about what problem to actually apply it to? Would > it be to run extractions to create development and reference guides - > ie. different from the typical user guides that a continuation of the > wiki/newhelp provides? Our to collect the usage documentation we have > + add lots of documentation we don't have today, and make some sort of > official trac-book to accompany major and minor releases? > >
Sphinx is indeed nice, but I'd rather see it's usage at the level of generating the API docs rather than for the TracGuide. I've started some months ago to clean-up the API docstrings in order to produce a reference manual using epydoc, but I stopped that effort as I found no good solution for the docstrings that should stay in Wiki markup (like the config options doc for TracIni and the wiki macro documentation). I had a look at Sphinx, and I have the impression it might be easier to extend it so that it could handle both styles. > Increasing the quantity and quality of official published > documentation on the project is a massive undertaking - regardless of > how it is done and with what tools. I'd rather we started in the other > end by agreeing on what documentation we (and plugin providers) should > provide to the community of users and developers. It then becomes > easier to evaluate and discuss individual tools for the job. > I agree, let's first discuss what is the documentation we want to provide, then which tools. I see three targeted audiences: 1. users, which have to figure out what they can do in Trac, and how to do it 2. administrators, which have to know how to manage and configure a Trac installation 3. developers, which in addition have to know the inside outs of Trac and have an API reference For 3. and most notably for generating the API reference, it makes no doubt we need a specialized tool, and I agree that Sphinx seems even better than epydoc in this respect (but a more detailed comparison in what we'd loose/gain should eventually be made). Nevertheless it's quite early in the game, as we don't have anything yet, so it seems to be the appropriate time to choose one or the other. I'm a little biaised against epydoc, because as I said above, I failed to see how to extend it so that it could handle the wiki markup parts. Now, for 1. and 2., the first remark is that we until recently didn't make a difference between those two audiences, and the structure of the TracGuide somewhat reflects that. For 0.11, I've made two main sections in the TracGuide page, but that's not really enough. What would be actually needed is two guides. The Trac User Guide could even be much more "user" oriented, being more visual (snapshots). It should show how to use Trac and for that there should be two levels: - introductory level, suitable for a 2 minutes reading - reference level, like the complete WikiFormatting guide The Trac Admin Guide should also eventually have those two levels, like a quick install and setup guide (which would eventually be displayed right after the installation) and also a more in-depth reference guide for all the various deployment and troubleshooting situations. Speaking of troubleshooting, a cleaned-up FAQ would be of a tremendous help ... for the help system. Now, where would that documentation (for 1. & 2.) come from? We don't start from nothing here, we already have a TracGuide which has evolved over the years, since Trac's inception. During the +2 years of 0.11 development (and even before since the 0.9 and 0.10 days), I've heard a lot of complaints about our poor documentation or lack thereof, but I've seen little activity in this area, so I find it hard to believe that a change of documentation format or tools would make a difference and that would suddenly motivate us to write more or better docs. Quite to the contrary, I find it critical that we continue to offer the possibility for our users and contributors to freely edit the TracGuide related pages on t.e.o, as those contributions are essential in keeping the documentation alive. Those contributions must be easy to integrate back in the official documentation, without requiring a format translation. So for me this is a strong argument in favor of keeping the user and admin documentation in wiki markup. The second argument is that if the TracTeam (tm) doesn't use its own wiki formatting and rendering chain, why should others trust it for writing their own documentation? If there are problems with that formatting or the rendering chain which makes it a sub-optimal solution compared to other tools (in the same category), then our "job" would be to fix it. Otherwise by the same kind of argument we could have switched to say, Roundup for our bug tracking needs, if some had considered it would have been better than Trac in this respect. Well, at least some people have faith in what Trac can do: http://www.packtpub.com/article/software-documentation-with-trac And I don't see why we should stop improving Trac abilities in this domain. Here are some of the relevant work items: - the WikiEngine refactoring which will make it possible to generate structured output (e.g. Genshi events or docutils nodes, so that we could hijack the docutils writers for generating the static documentation) - Section editing (#1024) so that big pages like the FAQ could be easily edited - Much improved table markup (the reST table markup is unbearable) - Lots of possible minor improvements to the syntax and rendering, in order to make writing documentation a more enjoyable experience (i.e. we have full control over the feature set) Bottom line: Improving the documentation system for Trac should motivate us to make Trac better at writing documentation, not prompt us to ditch Trac in favor of another tool for doing that job. -- Christian (PS: I'll discuss the newhelp branch in another mail, as that's a separate topic, which is format agnostic) --~--~---------~--~----~------------~-------~--~----~ You received this message because you are subscribed to the Google Groups "Trac Development" 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/trac-dev?hl=en -~----------~----~----~----~------~----~------~--~---
