Switch to docute documentation site generator

[sebinbenjamin]

Sets up docute to replace readthedocs. Fixes #1974

@lovell I've tried to include everything from https://sharp.pixelplumbing.com . Please have a look.

Tasks

• Retrieves versioned markdown files from GitHub, via jsdelivr
• Customise URL router to redirect to existing readthedocs URLs
• Define navigation bar (with logo) and sidebar
• Custom Footer
• Sends anonymous usage data to GA .
• Verify correctness of links in all pages.

I think the following might also be good. I could create a seperate issue/PR if they will be useful.

Additional

• Search feature - Maybe https://community.algolia.com/docsearch/ . Related Build a local search plugin egoist/docute#21, Build a local search plugin egoist/docute#261
• Configure documentation.js - Is it possible to add #title to generated .md files, like in install.md and performance.md
• Offline support - https://docute.org/guide/offline-support.

[sebinbenjamin]

Note: Links are currently pointed to my forked branch https://github.com/sebinbenjamin/sharp/edit/master/docs as I needed a new tag v0.23.4-alpha for testing. Needs to be changed before closing the PR.

Also do share the GA Tracking ID.

[coveralls]

Coverage remained the same at 100.0% when pulling 98b3872 on sebinbenjamin:master into d0feb41 on lovell:master.

[lovell]

This is amazing, thank you.

For the previous versions, readthedocs will be going away, so ideally these will come from GitHub too. The markdown files in docs/ are all tagged by version so I was hoping we could use something like https://docute.org/guide/customization#versioning for this.

The GA code is UA-13034748-12 (this is the user_analytics_code from https://sharp.pixelplumbing.com/en/stable/readthedocs-data.js)

Sadly documentationjs does not produce page titles for markdown output but we could define a custom plugin to replace the <!-- Generated by ... with <h1 class="page-title">Name of API section</h1> a bit like the example in https://docute.org/guide/plugin

[lovell]

Please can the copyright and licensing notice remain in this file.

[sebinbenjamin]

Oh ! Missed it. Sorry about that.

[sebinbenjamin]

For the previous versions, readthedocs will be going away, so ideally these will come from GitHub too. The markdown files in docs/ are all tagged by version so I was hoping we could use something like https://docute.org/guide/customization#versioning for this.

I tried versioning but got stuck with the file name requirement. I think that docute by default wants the landing page markdown file to be named as README.md, but we have it named as index.md for readthedocs. I am not very familiar with vue.js components/plugins, but am guessing from this code that we would not be able to override it. I could try putting up a feature request at docute for a custom default landing page filename. 🤔

The GA code is UA-13034748-12 (this is the user_analytics_code from https://sharp.pixelplumbing.com/en/stable/readthedocs-data.js)

Thanks. I'll just put the this in.

Sadly documentationjs does not produce page titles for markdown output but we could define a custom plugin to replace the <!-- Generated by ... with <h1 class="page-title">Name of API section</h1> a bit like the example in https://docute.org/guide/plugin

Nice. Let me check it.

[lovell]

I've merged this to the wit WIP branch via commit 3925689

Rather than provide docs for loads of older versions, I've added @since tags to some of the API to indicate the version from which it was made available.

These new docs, for the forthcoming v0.24.0 release, can be temporarily viewed at https://pixelplumbing-sharp.firebaseapp.com/ for now. I've configured Firebase to handle all the redirects - see https://github.com/lovell/sharp/blob/wit/docs/firebase.json#L22

I'll update the main documentation URL to point to this after sharp v0.24.0 is released.

Thanks again for all your help with this @sebinbenjamin - I think this PR makes you the 100th contributor to sharp!