Add docs.py script to support localization build (static and live)

[fflorent]

This PR takes the docs.py script from FastAPI and adapt it to make it work here.

Also just like the previous PR, you may merge it if you approve, it is meant to have no consequence on the resulting website.

Here is what docs.py offers:

$ ./docs.py --help
Usage: docs.py [OPTIONS] COMMAND [ARGS]...

Options:
  --install-completion [bash|zsh|fish|powershell|pwsh]
                                  Install completion for the specified shell.
  --show-completion [bash|zsh|fish|powershell|pwsh]
                                  Show completion for the specified shell, to
                                  copy it or customize the installation.

  --help                          Show this message and exit.

Commands:
  build-all         Build mkdocs site for en, and then build each language...
  build-lang        Build the docs for a language.
  langs-json
  live              Serve with livereload a docs site for a specific...
  new-lang          Generate a new docs translation directory for the...
  serve             A quick server to preview a built site with...
  update-languages  Update the mkdocs.yml file Languages section including...
  verify-config     Verify main mkdocs.yml content to make sure it uses the...

Untranslated page fallback to the English version, with a warning asking for help to translate the content. Also images / screenshots can be localized too! They just have to be put in the ./help/{language}/docs/images folder. If they are missing, the image from ./help/en/docs/images is used. All of this thanks to the mkdocs hooks!

How it looks like

A page with untranslated content looks like this:

The language selector

Also implemented the selectbox that switches the language (to make it work, run: ./docs.py build-all and then ./docs.py serve):

recording.mp4

TODO

Old todo list:

•  Use ./docs.py in build-doc.sh
• Moar testing (new_lang, build_lang, ...)
• Rework git commit messages (the first commit is meant to add docs.py without any change)
• Add missing-translation.md and offer a link to the documentation in English
• Credit Sebastian Ramirez in README
• Update README instructions
• Add assets missing in target language

[netlify]

✅ Deploy Preview for grist-help-preview ready!

Name	Link
🔨 Latest commit	4d7814a
🔍 Latest deploy log	https://app.netlify.com/sites/grist-help-preview/deploys/65df55022a95ad00074aeed2
😎 Deploy Preview	https://deploy-preview-313--grist-help-preview.netlify.app/
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[fflorent]

I read again my code after the weekend and found that I missed that part.

This part is meant to localize the section titles and the pages.

Whereas Fastapi handles localizing the sections by having an index.md file per section (for example tutorial in en and in fr), grist-help doesn't. Also it works for the files in FastAPI because they are only described only with their names at the contrary of what is done in grist-help.

I am removing this function and the hook (at least for now), and will try to find a way to translate the sections later.

[CamilleLegeron]

We are inside /examples folder, why not write ./images/2020-08-invoices/final-invoice.png

[CamilleLegeron]

To have same shape with newsletters folder ? Do you know why there is images in examples folder and directly in en/docs

[fflorent]

My guess is that it's specific to examples. That being said, probably these images could be moved to ./help/en/docs/images/examples/.

Grist Labs: what do you think of that?

[fflorent]

Made two distinct successive commits:

• 85a3874 in which I simply change fix the relative links;
• c17431e in which I moved the example images in help/docs/en/images/examples

Therefore if the latest one is not what we would want, we may revert it.

[fflorent]

I just fixed two little things after having made an internal demo:

• ✅ The background color of the language selector;
• ✅ Made possible to translate the warning info box when a page is not translated yet;

[paulfitz]

Great, everything is working for me in testing. Some comments.

[paulfitz]

That command says Make sure you run the build-all command first, should that be added first?

[fflorent]

That should be fixed in: 10aa15b

[paulfitz]

Thanks @fflorent ! I think this is good to land. Thanks for doing this all carefully and incrementally.