Documentation integration

[eine]

ATM we have multiple sources of documentation/information:

• Help modal box in the frontend, which contains frontend keyboard shortcuts. See https://github.com/filebrowser/frontend/blob/master/src/components/prompts/Help.vue.
• Home at https://filebrowser.xyz/. See https://github.com/filebrowser/filebrowser.github.io.
• Docs at https://docs.filebrowser.xyz/. See this repo.
• godoc at https://godoc.org/github.com/filebrowser/filebrowser. See golang sources at https://github.com/filebrowser/filebrowser. Also, see #x/pkgsite: generate static docs golang/go#2381.
• CLI markdown/man documentation generated with spf13/cobra. See https://github.com/filebrowser/filebrowser/blob/master/cmd/docs.go.
• HTTP API, still to be written. See Document HTTP API #1.

Since all of them can be rendered online, I think it'd be interesting to integrate all of them in a single static site and embed it in filebrowser. This would allow users to use and read the documentation of filebrowser even when offline or in isolated local networks.

[hacdias]

Hello @1138-4eb!

It would be great if we built a Hugo website with a script that gathered the info from GoDoc+CLI and merged it with the current content. We could then have only one website and also bundle it with the binary.

Personally, I really like the idea and I'd like to take care of this effort if you don't mind. And then we could eventually merge it with filebrowser.xyz. Eventually.

[eine]

It would be great if we built a Hugo website with a script that gathered the info from GoDoc+CLI and merged it with the current content. We could then have only one website and also bundle it with the binary.

That's what I thought. However, it is easier said than done:

• Hugo was designed for blogs and similar kids of site. So, it is hard to find a theme/template that suits our needs. However, there are some interesting examples: https://docs.pupil-labs.com/ This was discussed in https://discourse.gohugo.io/t/hugo-as-a-documentation-tool/112/46
• I don't think we can keep the GitBook as is and (easily) use Hugo at the same time. We need to either pick one of them, or do some heavy preprocessing to remove GitBook code snippets from the sources, before we pass them to Hugo.
• godoc seems not to be designed to allow the generation of a static site and/or to generate markdown sources. However, there is a third-party project that allows to do so: davecheney/godoc2md.
• The CLI sources generated by Cobra seem to be well-suited for Hugo.
• There are some cool HTTP API documentation sites which I believe that are generated with Hugo, such as Docker's (https://docs.docker.com/engine/api/v1.37/), but I don't know if the templates/themes are publicly available.

Moreover, we have some kind of circular dependency in the build process:

• We need filebrowser in order to execute filebrowser docs and generate CLI documentation sources.
• We need CLI documentation sources to build the site with Hugo.
• We need the output from Hugo in order to build the frontend and generate the rice-box.
• We need the rice-box to build filebrowser.

To work around it, we can either generate the CLI documentation with go run, or we can build filebrowser twice (one with docs and another one without them).

Personally, I really like the idea and I'd like to take care of this effort if you don't mind. And then we could eventually merge it with filebrowser.xyz. Eventually.

Right. Just let me know if you need any help.

[hacdias]

After some research I came to find Docusaurus which is a documentation static generator by Facebook. They're currently working on v2 which will bring some improvements. Personally I enjoyed my first try of using it (see 'docusaurus' branch and run it please). Although the styling is not much customizable in this version (it will be in the next one) so we can'tr have collapsible menus in the sidebar which makes it really ugly.

On the other hand, I really love GitBook as it provides amazing Search support and it's prettier, easier to use... and supports tabs (there's an issue for this on docusaurus too).

I see two options:

1. Use docusarus as our tool despite the bad looks (until v2 is out) and put it at filebrowser.xyz
2. Keep using GitBook and don't provide offline documentation.

I couldn't find a better static generator directed to documentation. Will wait on feedback.

[hacdias]

/cc @1138-4eb

[hacdias]

Just an update here: I also see that Docosaurus V2 is on the way. Hopefully after it is released, I can take a look at revamping our documentation and embedding it into the binary itself. Although it seems to take a bit of time yet. Perhaps going with Hugo would be a nice option. I'll give it a try.