Changes to userguide and python examples

[giovanni-rosotti]

Improvements to userguide and python examples. Also added an appendix with the reference of the functions defined in facade, generated automatically by sphinx. Looks nice - will need to go through all comments in facade and modify them though.

[rbooth200]

I agree the changes to the userguide looks good. I see you've changes loads in the python, but it seems to be (mostly?) just the comments.

Do you know if it is possible to use the same format for the listings code as the sphinx code? The listings code can be hard to separate from the text at the moment,

[giovanni-rosotti]

You mean the comments in facade.py? That's because they then become part of the userguide (in the appendix), providing a reference for each function. I think now with the slides+tutorial in the userguide (which I also expanded)+function reference there should be enough material for larning how to use the python library (but let me know if I am wrong).

About the listings, do you mean the ones in line (i.e. command \lstinline, although that's not consistent because sometimes we still use \var) or the scripts that have been included? I do think we can improve their font and style... if you have suggestions they're welcome!

[dhubber]

I just looked at the new userguide. It looks pretty nice. So, I'm guessing all the additional sphinx stuff gets compiled automatically when we type 'latex userguide.tex'?

My only issue is with the code font, which I think we should change because (a) the letter font itself is a bit unusual for code, and (ii) for some reason the letters are too spaced out in some places which makes it odd to read. If there were a simple of way of keeping the 'var' style font, but preserving the syntax highlighting, that would be great.

[giovanni-rosotti]

The appendix is automatically compiled, yes, by running 'latex userguide.tex' because I put also the sphinx generated tex file under version control. If you want to update the references you need to run sphinx - just run 'make latexpdf' from the analysis folder.

About the font, try adding basicstyle=\ttfamily to the \lstset command soon after begin{document} - it seems to improve the situation, what do you think?

[rbooth200]

The font is definitely an improvement

[dhubber]

Yes, I also think that's an improvement. For some reason, I just think that font looks better for the code (at least relative to the font for the normal text), obviously matches the variables/code that use \var{..}, and there does not appear to be so much a gap between letters in the code (there's a bigger gap than using \var{..} but that's because that environment is trying to maintain uniform spacing between characters in the code I guess, which is fine here).