Create a nice website for the developer's documentation

[davidculley]

Added a minimal proof of concept that compiles the .md files in /docs/ into a beautiful website (using MkDocs) and then hosts that website using GitHub Pages.

The website should become available at the following URL after merging this pull request:

https://ankitects.github.io/anki/

Browsing that website should provide a better experience than the .md files rendered by GitHub.

I can continue work on this website if it is considered useful.

For a preview of how this could look like, see (for example) the documentation of FastAPI.

[brishtibheja]

I personally like mkdocs, but mdbook is already being used for the manual/faqs so that is probably a better option for this website. (I'll also mention that a subdomain of ankiweb.net can be used here, although this one's fine IMO.)

[davidculley]

Thanks @brishtibheja for the ❤️ and your suggestions.

mdbook is already being used for the manual/faqs so that is probably a better option

That's a valid suggestion.

Can mdBook auto-generate such a site from docstrings, as MkDocs can (with the help of the add-on mkdocstrings? In other words: Can mdBook generate HTML documents from Python docstrings? I genuinely don't know because I'm not familiar with mdBooks.

If not, one could pose the question whether the developer's documentation absolutely needs to look and feel like the user's documentation. So a decision between two options can be made:

• Stick to mdBooks, not just for consistency of the look and feel but also because the core developers are already familiar with it.
• Use MkDocs for this particular use case if it offers new features. Non-developers won't see this developer's documentation, and developers might perhaps not care that much if it looks different than the user manual as long as it looks nice and they get from it what they want from it.

Looking forward to opinions. 🙂

a subdomain of ankiweb.net can be used

Agreed, using a subdomain rather than the URL issued by GitHub Pages could be a next step. This pull request is only the minimal proof of concept. 🙂

[brishtibheja]

I am not a developer really so I cannot tell you about that. I do know there are alternative renderers (the manual). Perhaps dae will know better about mdbook.

[dae]

I'm afraid this feels like adding more maintenance burden for not a lot of gain. The files in docs/ are not large, and it's expected that developers will typically be reading them from a checked out commit.