What should we use for online documentation browsing?

Question

I'm the project lead of a small Linux distribution and we are writing our user documentation in DocBook (XML). I'd like to host the documentation on a Web server somewhere, so people can refer to the documentation before installation and to troubleshoot on another computer if their system has an issue.

It'd be nice to have an interface somewhat like OpenPOWER's documentation or Fedora Documentation.

Must-haves:

• Open source license.
• Support for multiple versions of our distribution, and multiple books per version (ex: Adélie 1.0: Installation Guide, Admin Guide; Adélie 2.0: Installation Guide, Admin Guide)
• Permanent URLs (/version/bookname/chapter or such "clean" URL would be a bonus).
• Multiple language support.
• No JavaScript, or the ability to function without JavaScript.

Nice-to-haves:

• Good CSS that supports things like @media print for printing and graceful degradation for screen readers.
• Ability to serve PDF or EPUB copies of books for archival / offline reading.
• Server-side "search" feature to search books. For instance, "install software" could show a result for how to use our package manager.

I'm not even sure if such a system exists, but if it does I cannot find it anywhere. Right now I am manually converting the docs to MediaWiki and serving it off that, but it is not a very nice solution and doesn't support the kind of theme or multilingual support that we want to offer.

The software can run on any open-source OS that supports either x86 or PowerPC, but it'd be nice if we could "self-host" on our own Linux distro. (Obviously we would have to package it.)

Thanks for any suggestions!

Answer 1

One possibility to consider is to switch your documentation effort to ReStructured Text, (there are python utility scripts about, such as this, that can help), and then use Sphinx to generate multiple formats, with themes and a lot more and you can use plug-ins that add docbook output to sphinx and if necessary you can use pandoc to generate any that you need but are missing. Sphinx comes with about ten built in themes or you can create your own.

For a Sphinx aware hosting option Read The Docs is a great option. It supports themes, has full text search, is git, hg, svn & bzr aware and will rebuild your documents via webhooks when you push changes to the VCS with github and bitbucket integration. It supports versioning via tags and can host multiple versions of your documentation, with support for I18N. There is support for Canonical URLs. It also offers downloads of documents in multiple formats:

Everything mentioned above is Open Source.