v0.2.x docs

[nickhand]

we need to fully document the updated v0.2.x branch

[nickhand]

I'm experimenting with using the bootstrap sphinx theme and building on readthedocs. A preliminary version with a rough outline is here:

http://nbodykit.readthedocs.io/en/docs/

@rainwoodman what do you think?

Borrowing a bit from the design of yt's docs, we can have quickstart notebooks to get people up and running and also a cookbook of recipes as examples...these can range from simple code snippets to the more involved scripts that we use in our research. We can use the matplotlib plot to execute scripts that make plots and the nbsphinx extension to display notebooks. See http://nbodykit.readthedocs.io/en/docs/cookbook/index.html as an example of what this might look like. Readthedocs does have a rather short time limit, so we might need to generate these plots locally and upload them to make the build process purely static, but we can see how that goes.

[nickhand]

If we wanted to run all of the recipes during, say, the testing runs on Travis, we could also upload the docs to GitHub-pages directly from Travis. I think the only additional feature RTD adds is the ability to track and display different versions/branches.

[rainwoodman]

I like the layout, but

• the contrast of the main text is low, and
• the font is too narrow. It feels all smudged.

I think the most important guide for styling documentation is readability -- so what about making using a fatter font-face, and make the main text a bit darker, either adding more weight (wider strokes) or increase the darkness? Limiting the number of words per line is also quite important, especially nowadays the monitors are super wide.

About building, is it possible to upload to a version when travis is building a tag? This way seems like we can get around the time limit of rtd?

[rainwoodman]

Adding this to the stylesheet of body seems to be good enough.

font-size: 24px;
color: #505050

[nickhand]

where did you put that css? I can't seem to get that to work.

I don't think you can upload docs to RTD...it needs to be built by them at the moment.

[rainwoodman]

Hmm. I tweaked it in Firefox but didn't change the template. I think with sphinx you can overwrite the template or add additional assets?

I am not sure how this works with rtd though. The relevant place seems to be http://docs.readthedocs.io/en/latest/theme.html

[nickhand]

Okay take a look now, @rainwoodman. So far, I've got the install page and API outline up to date. I think it's looking pretty good so far!

[rainwoodman]

yes. I agree the new theme looks effective.

two points after a first read:

• dask was not significantly mentioned in the overall chapters. Given it is quite central, and several people have wondered what it means dask.array(....) when echoing a column, it may be useful to describe this.

• Another place that may need extra care is the usage of the FileCatalog subclasses -- because they are generated a user cannot see the usage in an explicit docstring from the source code. One way to get around this is in the code add a link to the generated documentation where there are examples.

[nickhand]

FYI @rainwoodman , I am going to open a PR shortly so can merge in what I have so far...

[nickhand]

The first large import of the new docs was merged in #370.

Beyond the obvious editing, etc, the remaining things to be done include:

• [x] Finish introduction section
• [x] Finish TaskManager section
• [x] Finish Help sections for developers + getting help
• [x] Quickstart guide?
• [ ] More cookbook recipes for simple tasks (NOTE: can link directly to sub-sections of notebooks in the Cookbook TOC; see the Painting Cookbook section)
• [ ] Finish the remaining algorithms: includes a tutorial and a cookbook notebook
  • [ ] ProjectedFFTPower
  • [ ] SimulationBoxPairCount
  • [ ] SurveyDataPairCount
  • [ ] Multipoles3PCF
  • [ ] FOF
  • [ ] CylindricalGroups
  • [ ] FiberCollisions
  • [ ] RedshiftHistogram
  • [ ] KDDensity

A few things need to be decided:

1. Is the quickstart section redundant with the Cookbook recipes? Originally I thought they were different, but most of the Cookbook notebooks do not require downloading any data...so users can use them to get up and running quickly. Maybe we just point to a few good notebooks to start with in the "Quickstart" section.

2. How do we want to handle downloading external data. Right now, each notebook uses mock data except for the BOSS DR12 notebook, which includes instructions to download the public data. How do we want to handle non-public, large data files? I am thinking of MPGadget data to demo or FOF data files to demo. Maybe we can host them on NERSC?

@rainwoodman