On Wed, Dec 23, 2009 at 7:53 AM, Adrian von Bidder <[email protected]>wrote:
> Heyho! > > I need to do a short evaluation of various documentation tools, preferably > OSS ones. I've met sphinx in the TurboGears project, and I think it > *might* > more or less fit, although it's a bit too techy for our needs. Your > comments appreciated. [ even more so if they reach me as cc:'s, though I'll > try to remember looking in the list archive. ] > I've used Sphinx for all sorts of projects, and It's always worked great for me. > ((( perhaps a more or less up to date comparison of such tools exists > already? Pointers welcome. ))) > > We need to produce end user documentation of our software in paper and some > kind of HTML snippets for online help. The full online version that Sphinx > will produce "for free" is also appreciated. The part where we're > struggling (and why we don't want to continue with plain oo.orgdocuments): > > * brands (we have OEMs, so we need to produce different versions with the > different names of the product and with different screenshots. From what I > see I should be able to do this with reST Substitutions, right? > Screenshots > would probably be just as different directories and a clever build script.) > reST substitution should do the trick for text. And I think you're on the right track as far as the screenshots go, too. I use Fabric to do something similar. > * translations (ideally we would be able to track which parts of a > document > -- as include files? -- are out of date in which translation.) > > Haven't done any translation work with Sphinx. > * changes (we work with svn, so we can track changes as is; perhaps > somebody even has written some kind of "change bars" extension? This is > not > mandatory.) > > One of the reasons I like sphinx is that the source files are plain text, and are easy to manage is almost any version control system. I'm not entirely sure what you're looking for here. > The paper version will have some significance, so basic control of page > layout is good, but it sholdn't be overrated; the PDF of sphinx' own manual > looks just fine. > > Don't forget to check out the rst2pdf project, which has a (expermiental) builder to create PDF docs using the ReportLab toolkit. > And it will need to be multi-platform. We're a mostly Linux company, but > our partners will need to (efficiently) edit text on Windows. What editors > do you suggest? And how complicated is it to install the necessary parts > for building sphinx documents on Windows? (I think we can live with 'only > html' and omit the TeX/PDF toolchain.) > > I use Sphinx almost exclusively from Windows, and have had no problems. Installing the basics of Sphinx is as easy as: Install Python Install setuptools/distribute Run "easy_install sphinx" from a command line That will get you all the basic tools that come with the regular Sphinx distribution. You'll be able to generate html and LaTex source files. Turning LaTex files into PDFs on Windows is a trickier proposition. I've managed it, but I don't recommend it. Try the rst2pdf stuff I mentioned above. As far as Editors go, I'm a big fan of SciTE, but Editra also looks pretty nice. Honestly, there's a bajillion and a half decent editors for Windows, free and non-free. I think this comes down to user preference. > A propos Tools: > > * we'll also need to export the current documentation into the new format. > Are there tools to produce reST from opendocument text documents? How > This might be kind of tricky...I'm currently converting a fairly large corpus of docs from xhtml into reST, and generating reST programmatically isn't the easiest thing in the world. Not impossible, just not easy. Here's an article that addresses this a bit: http://jimmyg.org/blog/2009/my-experience-of-using-restructuredtext-to-write-the-definitive-guide-to-pylons.html And a mailing list thread: http://groups.google.com/group/sphinx-dev/browse_thread/thread/77b0db51eb994775 And the sxw2rst tool here (no idea how well this works): http://docutils.sourceforge.net/docs/user/links.html#import You could also try using an internediate format, like html or docbook, and then converting to rst from there. You then will probably need to hand-edit your reST files to both correct errors, and add some of the Sphinx-specific directives, roles, etc. Or you could build your own converter, if you're a programmer. I recommend converting to some kind of XML format first if you want to go this route. But once it's done, it's very nice! Good luck! Kevin Horn I think the best you are likely to do is a partial conversion -- You received this message because you are subscribed to the Google Groups "sphinx-dev" 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/sphinx-dev?hl=en.
