Move the documentation to ReadTheDocs

[virtualtam]

As per #294:

• the online documentation has been spread over several pages
  • so is the local documentation
• both GitHub and the local copy lack a search feature
• handling of relative links is fuzzy with pandoc

ReadTheDocs uses the Sphinx documentation engine and supports:

• generation from SCM-hosted wikis
• Markdown syntax
• GIt webhooks (doc is updated at each commit)
• versioning: one version of the doc per branch and release
• exporting to HTML, PDF and Epub

Original issue content:

This is a follow-up to #294:

• the Wiki content has been spread over multiple pages and sections
• so is the local documentation copy
• it lacks a global Search feature, to quickly find information

Possible solutions (suggestions are welcome, it's been ages since I haven't written any JS ^^):

• Tipue Search, a jQuery plugin

[ArthurHoaro]

Isn't it a bit too much? Shipping jQuery and/or a client search engine lib for the documentation doesn't seem good to me. If I really need to search into the doc, I can either use Github, grep, find or even my favorite text editor.

[nodiscc]

• If I really need to search into the doc, I can either use Github, grep, find or even my favorite text editor.: github wiki has no search feature, most users will not use grep/find, text editor or document/html viewer remains the best option but
• Shipping jQuery and/or a client search engine lib for the documentation doesn't seem good to me either

Could we switch back to a single-page documentation (still separate user/dev documentation)? You can search it with a text editor/browser's Ctrl+F (not possible in multi-page docs). E.g. PDF documentation works well, and PDFs are single-page (well not really but they are flat). Single page allows you to take a quick look at the full contents by scrolling. Problems: TOC can get quite large (Add Back to top links?). Is there something wrong with this?

Semi-related

• Let's move the Backups page/section under Usage?
• https://github.com/shaarli/Shaarli/wiki/Copy-an-existing-installation-over-SSH-and-serve-it-locally and https://github.com/shaarli/Shaarli/wiki/Download-CSS-styles-from-an-OPML-list: scripts should not be inline, but in separate .sh/.php.example files.

I'm investigating pandoc templates for the HTML doc

[virtualtam]

Yes, it's definitely overkill :)

@nodiscc wrote on #294:

About switching to multiple pages + sidebar: I somehow miss the possibility to search for a word (Ctrl+F) in a single page (for example I was searching for htaccess, which was moved to the Security page

If it's not a problem not to have a search feature for the offline doc, this issue can be closed as Won't fix.

[nodiscc]

Is a single (1 dev/1 users) page layout ok? (+ moving sections/scripts). I can take care of it really quick (https://packagecontrol.io/packages/MarkdownTOC helps for the TOC)

The new documentation is great, it's just about the page layout.

[virtualtam]

If this navigation issue is specific to offline documentation, why not generate it in a more appropriate format?

E.g.:

• concatenate all pages
• use page titles as section names
• generate a single HTML and/or PDF document

[nodiscc]

It also affects online documentation (eg. https://github.com/shaarli/Shaarli/search?utf8=%E2%9C%93&q=htaccess does not return results from the wiki)
Edit: am I missing a hidden search feature somewhere?

[virtualtam]

Sadly, no... there seem to be no search feature for GH wikis O_o

Nor is the code indexed: https://github.com/shaarli/Shaarli/search?q=htaccess&type=Code&utf8=%E2%9C%93

Search is available through the github-wiki-search browser plugin, which requires some additional resources (Greasemonkey on FIrefox)

[virtualtam]

What about generating proper documentation on Read The Docs?

It uses the Sphinx documentation engine and supports:

• generation from SCM-hosted wikis
• Markdown
• GIt webhooks (doc is updated at each commit)
• versioning: one version of the doc per branch and release
• exporting to HTML, PDF and Epub

[nodiscc]

ReadTheDocs looks ok to me, if it solves the search problem, and if local documentation can be updated from it.

[virtualtam]

Which priority should this have? Would milestone 0.7 or 0.8 be OK?

[nodiscc]

Current documentation works, so no hurry :)

[virtualtam]

Thanks :)
I'm moving this issue to 0.7.0 and will try to provide a demo documentation on RTFD in a couple weeks

[nodiscc]

Be aware of http://alex.hyperiongray.com/posts/302352-pwn-the-docs (vulnerability in Readthedocs)

[virtualtam]

Thanks @nodiscc for the link!

The overall idea of this issue is to have the documentation using a flexible engine format (Sphinx); once done, static pages can be generated by anyone (with minimum Python & Markdown knowledge), and hosted anywhere (RTFD, github.io, personal server, etc.).

[virtualtam]

Just stumbled upon MkDocs, which:

• is a doc-generation tool similar to Sphinx
• takes Markdown as input (Sphinx uses reStructuredText); this is a huge plus as it would avoid converting the whole documentation
• is supported by ReadTheDocs (see Build Process)
• also provides tools to deploy documentation to other hosting services (e.g. GitHub Pages)

As I'll be toying with documentation generators & CI integration for several projects in the upcoming weeks, I'll use this thread to share my thoughts & feedback regarding the different tools & approaches ;-)

[mro]

know that one? http://xkcd.com/1343/

[nodiscc]

As long as the manual is searchable (either built in search, or CTRL+F on a single page) I think this nice. Having to maintain only a single markdown documentation for both the website and the wiki is a must have.

[nodiscc]

Note for self: I have a working* GH-wiki to HTML documentation (using make and pandoc) setup at https://github.com/RequestPolicyContinued/RequestPolicyContinued.github.io (site at https://requestpolicycontinued.github.io/) ^{(build.sh and Makefile).}. *It has some bugs.

I will try to improve the solution for both shaarli and requestpolicy so as not to duplicate effort. Progress will be tracked at https://github.com/nodiscc/pandoc-ghwiki-html

Mkdocs is also interesting

[virtualtam]

RTFD also provides a Markdown parser for Sphinx/docutils:

• https://recommonmark.readthedocs.io/en/latest/
• http://commonmark.org/
• https://github.com/rtfd/recommonmark

I stumbled upon it while looking at sources for the Mattermost IM service:

• https://github.com/mattermost/docs

Though I'm not a fan of having mixed rST / MD sources, this could help when converting existing resources.

[virtualtam]

Closed per #772