msimet / Stile

Stile: the Systematics Tests In Lensing pipeline
BSD 3-Clause "New" or "Revised" License
9 stars 6 forks source link

#17 Documentation #86

Closed msimet closed 7 years ago

msimet commented 8 years ago

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:

To build the documentation, make sure you have Sphinx installed and that Stile and all its dependencies are in your $PYTHONPATH, then type:

make html

to generate HTML docs, or

make latexpdf

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.

rmandelb commented 8 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...

msimet commented 8 years ago

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.

rmandelb commented 8 years ago

Yep, that works. Thanks.

rmandelb commented 8 years ago

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.

rmandelb commented 8 years ago

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

msimet commented 7 years ago

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!

rmandelb commented 7 years ago

Looks good to me. I say go ahead and merge.