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


Malcolm Humphreys <malcolmh...@...>
 

On 05/01/2011, at 9:20 AM, Jeremy Selan wrote:

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.
;) Thats good.

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.
It should be trying to do it all in the build/ directory, so this is a little strange.

Does this require users to have additional libraries on their system?
I have included all the additional libs for the html build, and install of Latex is the only external dep needed for the tex -> pdf build.

Should we make the docs building optional? (If your system doesnt have
the right libraries, it skips?)
It should skip the pdf build if Latex isn't found, but it seems it's found on your system and doesn't work.

Can you print out ${PDFLATEX_COMPILER} in the docs/CMakeLists.txt? Is this on OSX or Linux? It worked out of the box on debian 'testing' and centos.

On osx I have latex installed as part of the MacTex disto http://www.tug.org/mactex/ (1.6G eek?) To get cmake to pick it up I just set the PATH env to include '/usr/local/texlive/2010/bin/universal-darwin'

I was thinking of adding the 'doc' and 'pdf' targets just to the 'install' target so that they don't get triggered all the time when you call 'make'. You will still be able to call 'make doc | pdf' if your working on the doc strings.

I recon the 'pdf' target should be enabled by an option if it continues to be flaky.

I haven't added it yet but sphinx should be able to use autodoc to create the docs automagically for the python binding.

.malcolm


-- 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


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

Looks good to me. I did the merge, but disabled doc generation in the
top-level makefile by default. When you add the explicit target i'll
just roll that in too.

Thanks!

-- Jeremy


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

Malcolm, I wasn't able to build the docs at home even on OSX 10.6.
Would you try the master repo on your machine again (post merge) to
verify it works for you?

-- Jeremy

On Tue, Jan 4, 2011 at 5:01 PM, Jeremy Selan <jeremy...@gmail.com> wrote:
Looks good to me.  I did the merge, but disabled doc generation in the
top-level makefile by default.  When you add the explicit target i'll
just roll that in too.

Thanks!

-- Jeremy