Hi, Just wanted to introduce myself and let you know that there's another project out there using Sphinx. Thanks for a great tool!
I am currently in the process of migrating the documentation for XaoS <http://xaos.sourceforge.net> to Sphinx. The HTML output from Sphinx is at http://xaos.sourceforge.net/doc-trunk/ and the reST sources are at http://xaos.svn.sourceforge.net/viewvc/xaos/trunk/help/rest/. Below are some details about the migration process for those that are interested. (Sorry if this gets double-posted. The first time, I accidentally posted before I had joined the group and my message got moderated). Thanks, J.B. Langston XaoS Mantiainer Migration Process ============== User Docs (HTML) ----------------------- Our user manual was previously in a crippled subset of HTML that we dubbed XSHL, which was missing many features necessary for maintaining modern, attractive documentation. The conversion process was relatively straightforward. We already had a script to convert the XSHL to HTML. Then it was just a matter of cleaning it up with tidy and converting it with xhtml2rest.py from http://docutils.sourceforge.net/sandbox/xhtml2rest/xhtml2rest.py. I hacked a bit on xhtml2rest.py to reference the other pages using :ref: roles. This got me about 80% of the way there. After that, I have been slowly doing the necessary manual cleanup to get the rest of the way there. My restconv script and my modified version of xhtml2rest.py are located in our svn repository one level up from the reST sources, if anyone is interested. Developer Docs (Texinfo) -------------------------------- Our developer docs are currently in texinfo, and I'm working on converting those as well. First, I tried outputting them to HTML and using xhtml2rest.py on them, but I found that that approach loses an unacceptable amount of semantic markup from the original texinfo sources. Therefore, I'm currently cobbling together a texinfo to reST converter at http://xaos.svn.sourceforge.net/viewvc/xaos/trunk/doc/texi2rest.py?revision=384&view=markup. It uses the xml output generated by "makeinfo --xml" as its source. It's currently very much a work in progress, but I think it might be of interest to anyone else who has a lot of docs in texinfo. I started from xhtml2rest.py, and changed the XHTML node names to the corresponding texinfo nodes. It's still incomplete, even for my needs, which is the limited subset of TeX that is used in our documentation. I'll probably only get it far enough to process the subset used in our documents, and then hope someone else picks it up from there. Other Needs ----------------- Once I get all our docs successfully converted, I will start to work on a few other things I need in order for Sphinx to fully meet our projects needs. Once I get those done, I'll be happy to share them with the Sphinx mailing list. 1) Apple HTML Help Writer. This should be easily adapted from the Microsoft HTML help writer since they can both use the same basic HTML format. The big thing that is needed is adding an HTML anchor like "<a name="target"></a>" anywhere I have an internal hyperlink target like ".. _target:". Apple's Help Indexer uses these anchors to index the help files and provide context sensitive help. 2) Add support for context-sensitive help to the Microsoft HTML Help writer. Microsoft uses ALinks for this purpose (see http://msdn.microsoft.com/en-us/library/ms670173(VS.85).aspx). These are basically hidden index entries that can be used to pull up a specific help page using the API. I think it will be similar to providing context sensitive help for Apple HTML Help, except instead of embedding "<a name>" tags, I'll be embedding custom object tags. I haven't fully researched it yet. 3) Figure out a way to provide context sensitive help on Unix (GNOME). I'm thinking I'll probably just open up the appropriate page in a web browser. I'll have to tweak the HTML writer to output some kind of index file that my program can parse to find what HTML file to open for a particular keyword. --~--~---------~--~----~------------~-------~--~----~ You received this message because you are subscribed to the Google Groups "sphinx-dev" group. To post to this group, send email to sphinx-dev@googlegroups.com To unsubscribe from this group, send email to sphinx-dev+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/sphinx-dev?hl=en -~----------~----~----~----~------~----~------~--~---
