Add documentation to sdist

[benjaoming]

MANIFEST.in.dist should include the documentation.

The debian dist is built from an sdist, so that would immediately fix it. Windows already adds it in another way.

@cpauya does the OSX installer build from a PyPi sdist or do you create an sdist with setup.py sdist? Because in that case, fixing this issue will likely also add documentation to the OSX installer.

[aronasorman]

Not right now, although eventually it will, so it would be good to have it working through PyPi.

[benjaoming]

@aronasorman okay but does it use the output of python setup.py sdist because that was my impression...

[aronasorman]

No, it does not use the sdist yet.

[benjaoming]

Thanks, I got the link from Cyril to the setup.sh script :)

[rtibbles]

Status?

[benjaoming]

Well, the docs (html output like the stuff on RTD) are bundled in, and part of the sdist. What's remaining now is that they are served in urls.py?

It's a waste to ship the docs without making the accessible to users. And it's not that hard to add, let this be a release blocker, I shall attend to it.

[MCGallaspy]

It's already the case. However, the link only appears in the user menu when you're logged in.

[MCGallaspy]

The docs are served as static files: https://github.com/learningequality/ka-lite/blob/0.16.x/kalite/settings/base.py#L406

[MCGallaspy]

Link is created here: https://github.com/learningequality/ka-lite/blob/0.16.x/kalite/distributed/static/js/distributed/user/hbtemplates/navigation.handlebars#L47

[MCGallaspy]

Admittedly there's probably a much better way to present it.

[benjaoming]

Maybe we can assign this to someone who will come up with a suggestion of how to refer the user to the bundled docs?

[MCGallaspy]

I'll do it.

[benjaoming]

Just a quick note: Currently, we show documentation link to learners.. that doesn't make much sense?

[MCGallaspy]

that doesn't make much sense?

Who should be able to see it then?

[MCGallaspy]

My first thought is to create another tab (a la "Learn" or the User tab) as a top-level nav item. This can be enabled or disabled by user type.

[radinamatic]

Or maybe link the Learner User Manual page instead of the docs' index:
http://ka-lite.readthedocs.org/en/latest/usermanual/userman_learner.html

[benjaoming]

@MCGallaspy docs contain contents for quite different audiences, it's important to provide the right deeplinks.

IMO our User Manual is suitable for Managers and Teachers, not Learners, it's way too technical. If we want documentation for learners, it's a symptom of our whole UI being to complicated.. defeats the purpose.

If you can add a Help tab and only show it to logged-in users who aren't learners, and as @radinamatic mentions deeplink to the User Manual, that'd be sufficient IMO?

[radinamatic]

True up to the point @benjaoming.

Our docs as a whole are pretty technical, but the Learner User Manual page is down-to-the-ground enough (how to sign up, how to login). Granted maybe not for the kids learning how to count, but there is a lot of more advanced content in there (AP placement, college prep) that presume certain age and a minimum of tech-familiarity, if not "savvyness". Though I did add in my internal todo bucket, to think about the wording of the Accessing KA Lite topic and maybe re-locating the "Who is a “learner”?" phrase.