Re: Review: Added html and pdf documentation generation using sphinx


Jeremy Selan <jeremy...@...>
 

Whoa!!

These are beautiful docs, thanks for the hard work! The pdf is
awesome, as is the html. I think this will inspire me to keep all
docstrings up to date from now on.

When I run with your checkin, I get the following build error.

[ 40%] Building pdf doc
This is pdfeTeX, Version 3.141592-1.21a-2.2 (Web2C 7.5.4)
kpathsea: Running mktexfmt pdflatex.fmt
fmtutil: format directory `/usr/share/texmf/web2c' is not writable.
I can't find the format file `pdflatex.fmt'!
make[2]: *** [docs/CMakeFiles/pdf] Error 1
make[1]: *** [docs/CMakeFiles/pdf.dir/all] Error 2
make: *** [all] Error 2

Unfortunately on my machine I'm not able to make that directory have
write permissions. (and you shouldnt need root to do a 'make') What's
it trying to do? Can we have it do its work locally in the cmake build
dir? I also dont have pdflatex.fmt. in that directory.

Does this require users to have additional libraries on their system?
Should we make the docs building optional? (If your system doesnt have
the right libraries, it skips?)

-- Jeremy


On Mon, Jan 3, 2011 at 11:14 PM, Malcolm Humphreys
<malcolmh...@mac.com> wrote:
I have added sphinx OCIO document generation using sphinx, there are demo's of the output here:

html - http://malcolmhumphreys.github.com/OpenColorIO/
pdf - http://malcolmhumphreys.github.com/OpenColorIO/OpenColorIO.pdf

There are some still some issues with the index generation which needs to be fixed in the sphinx c++ domain.

I have only spent a little time reformatting the docs and have spent most of the energy getting all the bits together. If you want the pdf target to build you need to install pdflatex.

I chose the 'haiku' for the html this can be customised easily, see: http://sphinx.pocoo.org/latest/theming.html

Message:
Added html and pdf documentation generation using sphinx (http://sphinx.pocoo.org/)

Added ExtractRstFromSource.py which exports specially tagged comments in headers for sphinx to pickup. eg.

--snip--
//!cpp:class:: this is some super informative
// docs
class SomeClass
{
public:
   //!cpp:function:: the class namespace should still get set correctly
   void foobar2();
};
--snip--

Also fixed the install crud which Closes [#50]

Commit:
https://github.com/malcolmhumphreys/OpenColorIO/commit/1c7b8aab4c9daa427ecd8edb690672dbb0bee6a9

.malcolm

Join ocio-dev@lists.aswf.io to automatically receive all group messages.