Generating docs with Sphinx

[Nicola Nye]

Hi all,

Thanks for all your suggestions. With some extra caffiene in my system I
managed to solve the problem.

1) Manual graphviz install required in order to get dot.exe on my
system, along with some accompanying -Dgraphviz_dot directive to the
build. (Suspect this is optional but worth doing anyway)

2) My version of Sphinx (1.3.1) doesn't like captions on graphviz. Per
https://github.com/sphinx-doc/sphinx/issues/1788

Nic, I see you're running 1.2.2 and docs.cyrus.foundation is on 1.1.3.
Probably worth picking a version and consistently using it for now.
1.2.3 is the latest in the 1.2.* pile, or should we just go back to
1.1.3 for now? 

My eyes glazed over reading the release notes. Without knowing rst well
enough, it was difficult to know how many of the newer bugfixes/features
we would want to make use of.

http://sphinx-doc.org/latest/changes.html#release-1-4-in-development

   Nicola


On Fri, May 22, 2015, at 10:10 AM, ellie timoney wrote:
> Hi  Nicola,
> 
> The spinxoutput.txt file mentions:
> 
> > The full traceback has been saved in C:\Users\nnye\AppData\Local\Temp\sphinx-err-1niewvvh.log, if you want to report the issue to the developers.
> 
> Is that the same file as sphinxoutput.txt, or something different?  It
> might be instructive to look at/attach that log... maybe.
> 
> For what it's worth, I get a lot of warnings and errors along the way
> but it finishes successfully (Debian).  Don't recall what I needed to
> install to get it working, but now I just run "make html" in the
> cyrus-docs directory and it does its thing.
> 
> Cheers,
> 
> ellie
> 
> On Thu, May 21, 2015, at 02:56 PM, Nicola Nye wrote:
> > Hi all,
> > 
> > I'm trying to generate the docs using Sphinx so I can properly verify my
> > output.
> > 
> > Generation is falling over itself with errors. Warnings about missing
> > files and dodgy directives before it finally dies with an exception.
> > 
> > Does it work for anyone else? (Nic, Jeroen: I'm looking at you two!)
> > Anyone have any clues to get me functional?
> > 
> > Warning: I am on Windows so I'm prepared to acknowledge my environment
> > could be a factor.
> > 
> > Attached is the sphinx-build output.
> > 
> >    Nicola
> > 
> > 
> > Email had 1 attachment:
> > + sphinxoutput.txt
> >   53k (text/plain)