Closed msimet closed 7 years ago
I installed sphinx and was able to make the html dox, but when I tried the PDF, I got
! LaTeX Error: File `newfloat.sty' not found.
Are you doing this on coma? Is there some place with a latex distribution that has more stuff than the default? (I made the PDF successfully on my Mac, but I don't have the lsst stack installed there so I get errors when doing the html build.)
On a side note - I notice the README still says
Stile is a pure python package, no compilation needed. We do not currently have a utility that will install it in your system path for you, but as long as this directory is in your $PYTHONPATH, you should be able to import and run.
but we do have setup.py, so I think this can be updated...
Ah--I hadn't run it on coma, actually. There's no newfloat.sty on there as far as I can tell.
There's actually an issue about this on the Sphinx repo now--some Linux distributions don't include this file, so they'll be packaging it with future Sphinx versions just in case. The solution for now is to download newfloat.sty (I found a copy at http://math.sut.ac.th/lab/software/texlive/texmf-dist/tex/latex/caption/newfloat.sty ) and put it in a directory ~/texmf/tex/latex/. Then try running
kpsewhich newfloat.sty
and if that shows the file, latex compilation will work. How annoying!
I've updated the README on this branch, thanks.
Yep, that works. Thanks.
Some basic, silly comments on the PDF: The TOC page says CONTENTS at the upper right, and has a page number (i). Then I see a completely blank page without header/footer, then a page numbered 1 that says "Content:" on it (only that, plus header/footer), then a blank page 2 that does have a header+footer. So I think something weird is happening to the introductory material.
I know the README says this stuff, but I think the intro should say stuff about dependencies and installation, or if you don't want to worry about keeping the files in sync, you could say "see the README in the repo for information about dependencies and installation."
Hi folks, I think I have successfully addressed all the comments from...um...a year ago. If anyone has time to look over the changes and see if they make sense, that would be great!
Looks good to me. I say go ahead and merge.
Here's a draft of the Stile documentation! This isn't intended to be a finished pull request for you all to just sign off on--please edit anything you don't think is clear.
This PR required changing the style of a lot of docstrings, so the diff is huge. The things that really changed are:
doc/
directory, all of which are new;HistogramSysTest
, which added afield=
kwarg to be in line with the way we do theStatSysTest
;devel/checklist.txt
;stile/__init__.py
andtests/test_binning.py
.To build the documentation, make sure you have Sphinx installed and that Stile and all its dependencies are in your
$PYTHONPATH
, then type:to generate HTML docs, or
to make a PDF. (I think the HTML version looks better.)
make clean html
will rebuild all the files if you want that; otherwise it will only regenerate the documentation for any files that changed.There are some intro files (one each for systematics tests, data structure, and binning), then a bunch of
.rst
files read by Sphinx that contain automatically-generated documentation (those are all the "automodule" commands.) I'm happy to answer questions here about Sphinx formatting things if you want to change something but don't know how.