sfepy/sfepy — Issue #29: make the genDocXML + convert_doc work
Author: rc
Created: 2012-01-30 10:24:17+00:00
State: open

* finish the work on genDocXML to generate xml correctly
* improve convert_doc to generate the same pdf documentation as genDoc
* improve convert_doc to generate HTML

Migrated from http://code.google.com/p/sfepy/issues/detail?id=25

earlier comments

ondrej.certik said, at 2008-02-24T20:08:26.000Z:

XML -> pdf works now. I committed it directly to our repo. Sfepy needs a little
cleanup anyway, so let's clean it up when it works.

Usage:

$ ./gen

and a file "tmp/t.pdf" is generated. Look into "./gen" for details.

robert.cimrman said, at 2008-02-25T09:09:56.000Z:

Looks good. I see some glitches only in tables (the alignment character '&' is
printed - it seems that '&' gets translated into '\&') and in lines where a
regular text and a math text is mixed (the regular one is wrongly typeset in math
mode - 'termDefinition' needs to be improved). Nice work!

ondrej.certik said, at 2008-02-25T11:59:55.000Z:

Yep, those are known problems, which I didn't fix yet. I'll work on it today. In the
meantime, try to help me find a good name for it:

http://code.google.com/p/sympy/issues/detail?id=717#c18

ondrej.certik said, at 2008-02-25T21:07:54.000Z:

OK, so the code in the sfepy hg is always copied from:

http://code.google.com/p/prettydoc/

and everything is now fixed, except the tables, which I fix soon. Maybe you will not
like some of the formatting, but as the genDocsXML is concerned, it's only job is to
create tmp/terms.xml. We can then customize the output in prettydoc, see this issue
for that:

http://code.google.com/p/prettydoc/issues/detail?id=3

ondrej.certik said, at 2008-02-26T00:26:18.000Z:

I fixed the tables too, plus I implemented customizations, so I put a SfePy specific
customization to a separate file script/sfepyconverter.py, see ./gen how it works.

Please try it and comment. If you don't like some particular output, this should be
fixed in the custom file script/sfepyconverter.py

Only stuff, that is common to all projects should come to prettydoc.

I created a new issue 28 for the html printing.

Now please help me refine the customization + xml generation, so that we get the same
output. Then let's get rid of the old genDocs?

robert.cimrman said, at 2008-02-26T09:17:05.000Z:

I have fixed convert_doc.py to work with Python 2.4 - where should I commit to?
Into prettydoc? How should be the files copied around?

For the moment, I attach the patch here.

ondrej.certik said, at 2008-02-26T10:51:59.000Z:

I use python2.4.....

Anyway, if it's a fix to convert_doc.py, fix it in prettydoc and make sure all tests
run. Then copy convert_doc.py to sfepy verbatim.

That's my suggested way how to work with this. Any *local* modifications go to the
file sfepyconverter.py as explained.

robert.cimrman said, at 2008-02-26T11:00:18.000Z:

Strange... without the patch, this is what I get:

$ script/convert_doc.py --converter=script/sfepyconverter.py:SfePyDocConverter
tmp/t.xml tmp/t.tex
Traceback (most recent call last):
File "script/convert_doc.py", line 1058, in ?
main()
File "script/convert_doc.py", line 1033, in main
mod = __import__(mod_name)
ImportError: No module named script/sfepyconverter

with Python 2.4.4

ondrej.certik said, at 2008-02-26T12:23:38.000Z:

Weird. Maybe Debian's python 2.4 is different from gentoo's.

Anyway, it's in prettydoc now too. Please try to run prettydoc tests, as described on
prettydoc webpage and see if all is ok now.

robert.cimrman said, at 2008-02-26T12:49:23.000Z:

Ran 5 tests in 6.001s

OK

The generated files look ok.

robert.cimrman said, at 2010-04-26T13:42:19.000Z:

This is now obsolete since the documentation is generated by sphinx.