Switch to using a single source for both Latex and HTML documentation

[GoogleCodeExporter]

We already have Latex source for generating printable pdf version. However we 
also need HTML documentaion. Having two
different documentation sources would be a waste of time so need to come up 
with a solution that would allow us to use a
single source for both Latex(PDF) and HTML documentaiton. Luckly there software 
systems that allow for that. Please
have a look at this discussion: 
https://plus.google.com/110464871801965858778/posts/MRFwoEcBgmw where some 
person, presumably
from www.cvxr.com company claims to use Sphinx system (http://sphinx-doc.org/) 
for generating both pdf and html documentation
for CVX toolbox we use. You can check it out by yourself: PDF version is 
awailable here http://cvxr.com/cvx/doc/CVX.pdf
while HTML  - here http://cvxr.com/cvx/doc/ and very importantly - both these 
documentations are generated from a single source
claimed to reStructuredTex.

We have a tool (elltool.doc.run_helpcollector) that generates 
"chap_functions.tex" file in /doc folder which composes the 
part of out manual describing the classes, methods and functions. So we can 
update chap_functions.tex automatically. 

The person https://plus.google.com/110464871801965858778/posts/MRFwoEcBgmw 
claimed to use PanDoc (http://johnmacfarlane.net/pandoc/)
to generate Markdown representation of the documentation from Latex as the 
first step. Then he used the same PanDoc 
to translate Markdown into reStructuredText. As the second step he used Sphinx 
to generate both Latex and HTML from 
reStructuredText representation. This way should be completely fine for us as 
long as translation from Latex -> Markdown -> reStructuredText
is easy and not time-consuming. Otherwise we would have to switch to using 
reStructuredText as our main documentation source
and generate Latex from as opposed to generating reStructuredText from Latex 
each time we change something in Latex.

This there are two paths we could follow given that we know a complexity of 
Latex -> Markdown -> reStructuredText conversion.

Path a) Stick to using Latex as our primary source
Path b) Switch to using reStructuredText as our primary source. If we take this 
second path we would have to rewrite
elltool.doc.run_helpcollector so that it generates reStructuredText version of 
chap_functions.tex.

The result of this task should be

a) Decision which path we use
b) HTML documentation containing the same as 2013_ET_v2.0beta1_Manual.pdf
c) Wiki page describing the process of generating both pdf and HTML versions of 
documentation

You may contact this person to request additional information if you need to.

Original issue reported on code.google.com by heartofm...@gmail.com on 18 Sep 2013 at 2:31

[GoogleCodeExporter]

2) Please move "png" pictures from \doc folder into \doc\pic folder
3) Is there any progress with compiling Latex version of the documentation?

Original comment by heartofm...@gmail.com on 6 Nov 2013 at 11:21

[GoogleCodeExporter]

Original comment by heartofm...@gmail.com on 23 Nov 2013 at 9:09

• Changed state: Fixed