Transform to modern sphinx framework

[3ter]

As the gitbook-cli this documentation was using is now considered legacy for some time I wanted to modernize it using the sphinx framework and also furo (this can be dropped easily in case it gets deprecated).

Some of the advantages include

• (automatically) expanding/collapsible sections
• admonitions
• mouse hover tooltips

It's still using a (rich and extensible flavor of) markdown but could also be transformed into sphinx own format in the future.

I could use some help with the release process though (if you think it's a good idea after all 😊).

[3ter]

I just realized that there actually is a Gitlab mirror behind the GitHub front. I'm going to revert removing them... And probably add this info from to the README.

Still would appreciate some help with the release process. If you consider it a viable improvement that is.

[leafo]

I think it's worthwhile moving off of gitbook. I briefly experimented with https://github.com/steveklabnik/rustbook and it seemed to work okay with minimal changes but sphinx could be a better long term replacement. What encouraged your decision over the other options out there?

Keep in mind we currently we currently do do a server side merging of the itchio UI with the generated output of the rendered documentation to create pages like this: https://itch.io/docs/itch/ so having a generated documentation that is as close to plain HTML as possible would be desired if we want to keep that functionality

[3ter]

@leafo Thank you for the input. Yes, I recognized the merging and supposed that it was desired to keep that.

I actually have been inspired by the docs of the game engine Godot. I always found they are doing it right. I decided for a more minimal approach than the read-the-docs theme variant they are using (they quite heavily modified it and furo seemed perfect for replicating the current layout). I also tried mkdocs-material. It's cool (and hyped) but I still liked the design decisions for Sphinx better (how pages interlink for example, I disliked the nav: directive, I really found it cumbersome to add pages).

Too keep changes small I also decided to use the extension for Sphinx to use markdown instead of its restructured text.

Do you have ideas to help me with publishing it correctly? Should we again use Google Cloud like in the JavaScript file?

EDIT I forgot to say that I like how the Godot docs are separate from their main page. I accept of course if you want to keep it. I just think it adds unnecessary complexity and a top bar which distracts and takes space IMHO.