Migrate documentation to mkdocs

[hypergonial]

Summary

Reimplement the documentation in mkdocs material.

Deployments:

• ~~Github Pages~~ outdated
• ReadtheDocs

I think it is worth considering an alternative to readthedocs (like pages) given the performance of readthedocs is so abysmal comparatively, however, in that case, versioning needs to be considered.

Stuff missing/not done

• [x] ~~Docstrings were not adjusted for the new admonishment styles~~
• [x] ~~PR branch needs to be removed from github action triggers (or pages action removed entirely)~~ Pages action was removed

These will be done if #1806 is accepted and a documentation host is decided on, so this PR can proceed.

Related issues

Closes #1806

Feedback would be appreciated.

P.S.: I sneaked arc into the readme.

[davfsa]

Started working on this a while while back (https://github.com/davfsa/hikari/tree/task/mkdocs) but the main showstopper was https://github.com/mkdocstrings/griffe/issues/96 and eventually waiting for the module to come out of sponsor only territory, which seems like it is the case now.

Ill append the work I did onto this.

I also would like to not use github pages since repos have a size limit and we will quickly hit it with how heavy our docs are. Readthedocs will have to suffice for now, as well as maybe finding a nicer way to display the version switcher, which i have some ideas for.

Thanks for working on this!

[hypergonial]

Just tested how objects.inv behaves, and it seems like other docs still only get partial (albeit much more than none) information. The top-level module hikari is not picked up for some reason, and some objects like UNDEFINED or Resourcish are also not linked properly, unsure why.

This is from a fresh build of the arc docs pointed to hikari.hypergonial.com/objects.inv

[davfsa]

After some conflict merging, this is what I came up with.

If that looks alright, I can push it and we can see if it requires any tweaks

---

Note: I already have the admonition changes stashed, the only thing that would need changing is the links

[hypergonial]

After some conflict merging, this is what I came up with.

If that looks alright, I can push it and we can see if it requires any tweaks

Note: I already have the admonition changes stashed, the only thing that would need changing is the links

Not sure on that purple tbh, but otherwise looks nice, go for it!

[davfsa]

Pushed my changes, please have a look at lmk what you think/would like changed (anybody reading this is also welcome to see and try it out here https://hikari-py--1810.org.readthedocs.build/en/1810/)

Furthermore, when it comes to versioning, might be "ok" to leave it with the little widget at the bottom, since the only other thing I can think about is highjacking mkdocs mike integration and providing the version.json ourselves in the gh-pages branch (and then somehow figuring out how to disable the readthedocs widget)

[hypergonial]

Autoscrolling when searching is broken, it doesn't scroll to the object that was searched for. This wasn't an issue before the merge.

EDIT: This seems to be an issue on all deployments (mine updated as well :p)

[davfsa]

Autoscrolling when searching is broken, it doesn't scroll to the object that was searched for. This wasn't an issue before the merge.

Works for me :thinking:

---

Also, now that I get to use it a bit more, god is it painful to use when compared to the ones we currently have, at least in readthedocs.

Also, fun fact, one build of the docs alone is 36MB, which is quite high, so getting somewhere to host this could be feasible, but expensive after a while

[hypergonial]

Autoscrolling when searching is broken, it doesn't scroll to the object that was searched for. This wasn't an issue before the merge.

Works for me 🤔

Also, now that I get to use it a bit more, god is it painful to use when compared to the ones we currently have, at least in readthedocs.

Also, fun fact, one build of the docs alone is 36MB, which is quite high, so getting somewhere to host this could be feasible, but expensive after a while

That's why I suggested seeking alternative hosting. Readthedocs is really awful to use, but other hosts do not seem to have that issue afaict.

[davfsa]

That's why I suggested seeking alternative hosting. Readthedocs is really awful to use, but other hosts do not seem to have that issue afaict.

Any suggestions are welcome, I dont know any

[hypergonial]

Autoscrolling when searching is broken, it doesn't scroll to the object that was searched for. This wasn't an issue before the merge.

Works for me 🤔

Also, now that I get to use it a bit more, god is it painful to use when compared to the ones we currently have, at least in readthedocs.

Also, fun fact, one build of the docs alone is 36MB, which is quite high, so getting somewhere to host this could be feasible, but expensive after a while

Oh this works on Firefox but broke under Chromium, I just tested. That's fun. Maybe related to the removed slugify config?

[hypergonial]

That's why I suggested seeking alternative hosting. Readthedocs is really awful to use, but other hosts do not seem to have that issue afaict.

Any suggestions are welcome, I dont know any

One silly idea I had is that we could split the main offenders (hikari.channels and hikari.guilds) out into multiple files so that mkdocs doesn't freeze the whole browser trying to load those 2 pages.

[davfsa]

One silly idea I had is that we could split the main offenders (hikari.channels and hikari.guilds) out into multiple files so that mkdocs doesn't freeze the whole browser trying to load those 2 pages.

The main offender here is mostly hikari.impl.rest and hikari.api.rest, which we cannot split.

[hypergonial]

I did some more testing, on Chromium, even clicking items in the toc doesn't seem to work, the scrolling just stops briefly after starting. Maybe it is to do with the custom CSS you added?

[hypergonial]

I did some more testing, on Chromium, even clicking items in the toc doesn't seem to work, the scrolling just stops briefly after starting. Maybe it is to do with the custom CSS you added?

Yeah this is definitely the case, smooth scrolling breaks jump actions on Chromium.

[hypergonial]

Favicon is also failing to load on Chromium: (both mirrors)

[davfsa]

Yeah this is definitely the case, smooth scrolling breaks jump actions on Chromium.

Reverted it. Seems to only happen on large pages, its weird

[davfsa]

Favicon is also failing to load on Chromium: (both mirrors)

Its not even being requested through http, so its really confusing

[hypergonial]

Favicon is also failing to load on Chromium: (both mirrors)

Its not even being requested through http, so its really confusing

Yeah I don't understand it either, weird. Having the asset locally seems to fix this though.

[hypergonial]

Disabling instant navigation definitely helps, I'd keep it disabled.

[hypergonial]

Is there a way we can remove this level of unnecessary nesting inside hikari?

The index page could probably be moved up into Reference (and it made clickable)

[davfsa]

Disabling instant navigation definitely helps, I'd keep it disabled.

Good to hear, also improves mobile usage.

The last thing to figure out is the docs switch for readthedocs, which I will look into in a bit :)

Hopefully, in the soon:tm: future, we will also have less things to document and faster load times ;)

[hypergonial]

You broke the API reference landing page. :p Also the top-level hikari.__init__ should be documented somewhere otherwise it will be missing from objects.inv. (although said objects.inv has other issues too so idk)

[hypergonial]

Disabling instant navigation definitely helps, I'd keep it disabled.

Good to hear, also improves mobile usage.

The last thing to figure out is the docs switch for readthedocs, which I will look into in a bit :)

Don't forget the admonish fixes in docstrings & possibly doing smth about objects.inv

[davfsa]

You broke the API reference landing page

/reference/ never worked, if that is what you mean.

Also the top-level hikari.init should be documented somewhere otherwise it will be missing from objects.inv. Well then it needs to be added back, no getting around that one.

I rather have a "useless" drop down than potential issues somewhere else

objects.inv has other issues too so idk possibly doing smth about objects.inv

Mind dumping exactly what you mean? I havent had a look at it, but it should be alright

[hypergonial]

You broke the API reference landing page

/reference/ never worked, if that is what you mean.

Also the top-level hikari.init should be documented somewhere otherwise it will be missing from objects.inv. Well then it needs to be added back, no getting around that one.

I rather have a "useless" drop down than potential issues somewhere else

objects.inv has other issues too so idk possibly doing smth about objects.inv

Mind dumping exactly what you mean? I havent had a look at it, but it should be alright

https://hikari-rtfd.hypergonial.com/en/latest/reference/hikari/

This is where you get directed after clicking "Reference" in top nav.

[davfsa]

This is where you get directed after clicking "Reference" in top nav.

You are coming from an old page, otherwise it would redirect you to reference/hikari/api. And that "broken" page you see is actually an interesting 404, which i will have to have a look into. I pressume we need to ignore mkdocs one and use rtfm one

[hypergonial]

We could also use https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/#navigation-sections-with-sections to flatten the navigation a bit, perharps. But this can only be enabled site-wide, or not at all.

[davfsa]

We could also use https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/#navigation-sections-with-sections to flatten the navigation a bit, perharps. But this can only be enabled site-wide, or not at all.

That will not help, as it will just merge what we see as the left TOC with the right one if it can, which is just bloat

[hypergonial]

This is where you get directed after clicking "Reference" in top nav.

You are coming from an old page, otherwise it would redirect you to reference/hikari/api. And that "broken" page you see is actually an interesting 404, which i will have to have a look into. I pressume we need to ignore mkdocs one and use rtfm one

It seems like readthedocs breaks mkdocs's 404 page entirely, unsure why, it should look smth like this, and this works on github pages.

[davfsa]

The 404 issue will be fixed when the docs are actually deployed:

MkDocs automatically generates a 404.html which Read the Docs will use. However, assets will not be loaded correctly unless you define the site_url configuration value as your site’s canonical base URL.

https://docs.readthedocs.io/en/stable/reference/404-not-found.html