[Live-demo] osgeo live documentation as a booklet/handout

[Cameron Shorter]

On 5/12/2011 8:27 PM, Hamish wrote:
> maning wrote:
>> Excellent! I tried creating a pdf
>> using rst2pdf.  This is the process:
>>
>> # get rst docs from svn
>> svn co https://svn.osgeo.org/osgeo/livedvd/gisvm/trunk/doc/
> try also:
>
> $ cd doc/
> $ make help
> Please use `make<target>' where<target>  is one of
>    html      to make standalone HTML files
>    dirhtml   to make HTML files named index.html in directories
>    pickle    to make pickle files
>    json      to make JSON files
>    htmlhelp  to make HTML files and a HTML help project
>    qthelp    to make HTML files and a qthelp project
>    latex     to make LaTeX files, you can set PAPER=a4 or PAPER=letter
>    changes   to make an overview of all changed/added/deprecated items
>    linkcheck to check all external links for integrity
>    doctest   to run all doctests embedded in the documentation (if enabled)
>
>
> $ make latex
> ...
> reading sources... [ 16%] de/quickstart/ushahidi_quickstart
> reading sources... [ 16%] de/quickstart/virtualbox_quickstart
> reading sources... [ 17%] de/quickstart/zoo-project_quickstart
> reading sources... [ 17%] de/sponsors
>
> reST markup error:
> .../trunk/doc/de/sponsors.rst:33: (SEVERE/4) Problems with "include" directive path:
> IOError: [Errno 2] No such file or directory: 'contributors.rst'.
> make: *** [latex] Error 1
>
> (so I get the similar problems as you)
>
> # if that had worked you could then do LaTeX to dvi/postscript/pdf,
> # with any of the classic tools.
> $ pdflatex ...
>

Maning, I think that your efforts to make a PDF book will be an 
excellent addition.
Hamish is on the right track with his advice.

What I suggest is that we update our Makefile in order to supporting 
making PDF documents. Eventually, we should be able to type "make pdf", 
and pdf documentation will be created.

Are you familiar with to format of Makefiles? If not, it might be worth 
doing a quick refresher, then having a look at the "make html" 
directive, which we have been keeping up to date. (Look in the Makefile 
[1] for the "html: ...." directive).

We will need to update the "make latex" to have a similar set of 
dependencies to the "make html".
This will fix some of the errors you have been seeing.
Ie, update the latex directive to something like:

latex: sphinxbuild fix_header_links banner_links win_installer_links 
test_page css link_to_en_docs link_to_en_docs

[1] https://svn.osgeo.org/osgeo/livedvd/gisvm/trunk/doc/Makefile



-- 
Cameron Shorter
Geospatial Solutions Manager
Tel: +61 (0)2 8570 5050
Mob: +61 (0)419 142 254

Think Globally, Fix Locally
Geospatial Solutions enhanced with Open Standards and Open Source
http://www.lisasoft.com