Final docs review

[MCGallaspy]

Prior to release, take a careful look at the documentation. Create a documentation tarball for inclusion in installers.

[MCGallaspy]

The red border applied for element highlighting in the screenshots appears to displace elements slightly -- should just lay on top, instead of moving them.

[rtibbles]

Mike - perhaps use the outline property instead?
http://stackoverflow.com/questions/2748637/how-to-give-border-to-any-element-using-css-without-adding-border-width-to-the-w

[benjaoming]

@MCGallaspy I'm working on embedding the docs in another issue, #4348 and #4375

[jinchuika]

Did you added the suggestion in #4049? I find it really useful

[rtibbles]

I think @aronasorman is assigned to that, we will bug him about it today!

[MCGallaspy]

@benjaoming

I'm working on embedding the docs in another issue, #4348 and #4375

Do those issues relate to this one? I wasn't very specific, but to be clear I'm only reviewing the documentation for accurate content, good layout, etc.

[benjaoming]

@MCGallaspy

I was reacting on this part:

Create a documentation tarball for inclusion in installers.

...because what I'm working on is including them in the sdist.. but since this isn't part of the Windows installer, I guess we're talking about two different things here :)

[MCGallaspy]

@benjaoming if you need some files to include now, my suggestion is to grab a tarball/zipfile from RTD. If you can wait a bit for me to upload fixed-up screenshots, then you can also build the html yourself. This is the relevant logic for including docs. You just need to drop the html output of sphinx-build into the source directory's docs/_build/html/ subdirectory. Lemme know if this needs some tweaking to build a .deb file.

Edit: see also

ka-lite/kalite/distributed/hbtemplates/user/navigation.handlebars

Line 46 in 9ab838e

{{#if docs_exist}}

and

ka-lite/kalite/facility/api_resources.py

Line 187 in 9ab838e

"docs_exist": getattr(settings, "DOCS_EXIST", False),

[MCGallaspy]

I suppose we're done here.

[MCGallaspy]

Oof, actually, I haven't created a tarball -- but now that updated screenshots have been committed, it's as simple as running make html in the docs directory. That will create all the appropriate files in the docs/_build/html directory. Will upload tarball upon request.

[benjaoming]

@MCGallaspy actuall RTD has one:

http://readthedocs.org/projects/ka-lite/downloads/htmlzip/latest/ (still 0.14)

and

http://readthedocs.org/projects/ka-lite/downloads/htmlzip/0.15.x/

[MCGallaspy]

@benjaoming it's a single-page document.

[benjaoming]

@MCGallaspy grr, okay, why can't RTD be perfect... but it's in the right layout with anchors and everything :)

the new sdist in pypi has docs/_build/html included