Make docs branded/integrated

[gampleman]

For most technical products, the documentation is a pretty important piece of marketing: when seeing if a certain product will be suitable for my needs I judge the documentation quite early on - as it can tell me the actual technical details that often make the difference between something useful and useless.

However our documentation, while content-wise is quite good, leaves a lot to be desired in its presentation. The theme is boring and stock. There are no convenient links to get back to the product/website. It hardly says Aircloak on it at all (it does but in a barely readable gray-on-gray font).

[sebastian]

When doing this, let's please move away from gitbooks. The reasons are as follows:

• the open source project is no longer maintained and frequently breaks our builds
• search is broken and frequently causes the whole browser to crash/freeze

[edongashi]

Some gitbook alternatives:

• https://docusaurus.io/
• http://daux.io/
• https://www.mkdocs.org/
• https://docsify.js.org/
• https://docute.org/

[gampleman]

So, to recap a bit, we have the following desires:

1. Search
2. Actively maintained and bug fixed tool
3. Offline versions too (but can skip that if need be). It seems people actually do like to download the PDF version
4. Strong preference for something that doesn’t need to do ahead of time compilation, so we don’t have long build times when starting our system during development and during tests
5. Ideally uses a stack that won't be too much of a PITA to deploy (i.e. I don't really think setting up a PHP server just to serve docs is ideal).
6. Can be deployed on locked down infrastructure, i.e. isn't or doesn't rely on SAAS tools.

Looking at the tools above, each fails in some of these requirements:

• https://docusaurus.io/ fails in 3, 4, and 6.
• http://daux.io/ fails in 3, 5
• https://www.mkdocs.org/ fails in 4, 5 (I'm also not a huge fan of the output having worked with documentation for drf a lot)
• https://docsify.js.org/ fails in 3 xor 4. Being the most promising I spent some time trying to set it up and it seems rather inflexible, in that we might need to restructure our docs to fit the tool.
• https://docute.org/ fails in 1 and 2.
• https://github.com/rust-lang/mdBook fails in 3 (partially, it has suboptimal Epub support) and 4.

I also thought of building this ourselves as we already have a nicely themed web app. In my mind the parts that would take some effort are 1 (as we would either need to figure out how to do this server side or have a build step generating a lunr index) and 3 (where build a markdown to PDF tool is pretty doable, but hammering out the corner cases would take some effort).

Either way, I don't think I've found a solution that is a clear win over what we have unfortunately :(

[sebastian]

IF we go with build-our-own we could use the built in full text search functionality of SQLite too. It's fast and good from what I know.

I am fine with dropping the support for offline docs (i.e 100% happy dropping support for stuff other than PDFs, and 80% OK with dropping support for generating PDFs).

Being the most promising I spent some time trying to set it up and it seems rather inflexible, in that we might need to restructure our docs to fit the tool.

Could you please elaborate a bit on what would need to change to fit the docsify ?

https://github.com/rust-lang/mdBook fails in 3 (partially, it has suboptimal Epub support) and 4.

The samples look really ugly, but aside from that maybe it's the best option at the moment?

[gampleman]

I also feel mdBook might be our best shot and it is the most similar to gitbook, so the migration might be straightforward.

Could you please elaborate a bit on what would need to change to fit the docsify ?

So far it seems:

1. Would need to rename a bunch of files.
2. No support for transclusion, so we'd need to deal with that.
3. I couldn't get it to work nicely with proper URLs. That means that say /docs/deployment.html would turn into /docs#deployment. This is annoying, since all links to our documentation would be broken.
4. It has its own, custom, and entirely different styling framework, so making it look like we want could be pretty challenging.

Nothing I feel is a real dealbreaker, but it is annoying.

[edongashi]

I'm absolutely loving docsify. It has plugins for so many things!

• Tabs - needed for API docs
• Search - completely client side
• Mustache templating - if we want to plug the version number from a json file
• PDF export via plugin - not sure how good it is, but it's there
• No compilation step - all we need is to expose .md files from phoenix, client does the rest
• index.html where we can configure everything
• _sidebar.md file support for custom sidebar
• _footer.md file for custom footer with branding etc.
• Themes, code highlighting
• Plugin for glossary, copy snippet to clipboard button.
• We can tweak whatever we want with CSS considering it's just an index.html file. We can also inject scripts and such.

The only minus is that it has no {% include %} support. There's a plugin for that but I'm not sure if it works with search. Edit: this also works https://docsify.js.org/#/embed-files

We may need some restructuring to get it running properly, but I got a basic setup running in 20 minutes. There's 3 or 4 %include calls so it won't be too difficult.

If there are no objections I'll try a PoC implementation.

[sebastian]

If there are no objections I'll try a PoC implementation.

Go for it!