Tweaks to make to embedded documentation

[jamalex]

• Provide an easy way to link back to the KA Lite interface itself -- currently, no escape. Perhaps (eventually) embedding the docs directly within the KA Lite interface (having a view under /docs/ that maps paths, loads the appropriate HTML docs file, and renders it into the main page context in the content area)
• Allow link to docs even when not logged in
• Don't include "install guide"? Maybe? Or at least link to /static/html/usermanual/userman_main.html as the default page. Most of the sections other than "usermanual" are actually largely not so useful on an installed offline server, so we may want to just ship the "usermanual" portion?
• Don't include "View page source" or "View on Github" links, to avoid confusion.
• Don't include links in "Built with Sphinx using a theme provided by Read the Docs." text at bottom (or delete whole line)
• Change "Copyright 2015, FLE" to "Copyright 2015, Learning Equality, licensed under a Creative Commons Attribution-ShareAlike 4.0 International License".
• Remove online badges

Ad Removing online badges:

In 0.15, we started using an ReST README because it can be reused for the docs so we don't maintain the same stuff in multiple places. It would be nice if the offline build had the section with badges from online sources disabled, though

http://sphinx-doc.org/config.html#conf-tags
http://sphinx-doc.org/markup/misc.html#including-content-based-on-tags

[MCGallaspy]

I'd like to first address these in 0.15, and then create a patch for 0.14.x time permitting.

[benjaoming]

#4375 addresses that documentation is actually not part of what's currently distributed. That needs to be solved.

@MCGallaspy The release notes actually mention that we are going to have documentation for OSX/deb for 0.14 soon.

[benjaoming]

Don't include "View page source" or "View on Github" links, to avoid confusion.

The "Edit on Github" is IMO very important. Having a very very low bar for contributing to the documentation is important.

The documentation is intended for administrators / devs, so I think they can understand that it's pointing to an online location. Even if they don't have internet access, it'll just signal that this is an open source thing.

Whatever system is running KA Lite, it'll be full of internet references, it's just impossible to clean up :)

[MCGallaspy]

The release notes actually mention that we are going to have documentation for OSX/deb for 0.14 soon.

Including the documentation at all is quite separate from addressing this issue. If we wish to include documentation in 0.14 for other OSes, I think we should just drop in the static HTML (a la Windows) since it requires a minimum of effort, and focus on improving offline documentation in future versions. Otherwise I'm afraid we'll be ineffectively splitting our effort between many different versions.

Re: this issue, after giving it a bit of thought, I wonder if the best approach for creating offline documentation is to create another sphinx builder? I.e. something which instead of outputting html outputs Django templates. That will let us use template context variables to allow tighter integration with the app (back links, etc). Check out the sphinx docs on builders. My guess is that we could extend the default html builder to suit our specific needs here.

[benjaoming]

@MCGallaspy I thought you made a patch so that if docs/_build/html exists, it gets served, right? So I'm just gonna make sure that the next 0.14 patch release also has them -- that'd work, right? I don't think the docs need any updating for that to happen.

[MCGallaspy]

I thought you made a patch so that if docs/_build/html exists, it gets served, right?

Correct.

[jamalex]

The "Edit on Github" is IMO very important. Having a very very low bar for contributing to the documentation is important.
The documentation is intended for administrators / devs, so I think they can understand that it's pointing to an online location. Even if they don't have internet access, it'll just signal that this is an open source thing.

The online docs definitely need this -- and yes, those are used more by admins/devs. The offline docs bundled into KA Lite (that's what this issue is about) are the opposite -- they're going to be used primarily by teachers and learners (and... offline), and hence links like this are just a distraction/confusion.