Migrate documentation to mkdocs #1810
Conversation
hypergonial
changed the title
|
Started working on this a while while back (https://github.com/davfsa/hikari/tree/task/mkdocs) but the main showstopper was mkdocstrings/griffe#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! |
This comment was marked as outdated.
This comment was marked as outdated.
|
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: |
Not sure on that purple tbh, but otherwise looks nice, go for it! |
|
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) |
|
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) |
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. |
- Regex used: `^ \.\. code-block:: python\n\n(( .+|\n)*)\n\n` - Replacement string: ` ```py\n$1\n ```\n\n`
- Regex used: `^ \.\. code-block:: python\n\n(( .+|\n)*)\n\n` - Replacement string: ` ```py\n$1\n ```\n\n`
Manual fixes
- Regex used: `\.\. (.+)::` - Replacement string: `!!! $1`
|
I have pushed the markdown fixes. All that would need to be fixed are the reference links using https://github.com/mkdocstrings/autorefs (included as part of the python handler of mkdocstrings) |
hypergonial
force-pushed
the
feature/docs-v3
branch
from
b13df05
to
417431c
Compare
davfsa
force-pushed
the
feature/docs-v3
branch
from
417431c
to
547ad2b
Compare
Are you working on it, or should I go over them? |
They are insanely tricky, since its not as easy as a search and replace, and there are probably hundreds (edit: there are 1130) of them. I will work on it tomorrow, most probably end up parsing all the docstrings, trying to link stuff and figuring out which ones link and replacing those |
Any updates on this? Should I try to take a look myself? |
|
593 more to go (down from +3k) I quite urge you not to touch the branch, as rebasing this will be insanely painful |
Dear god.. Understood! |
Somehow managed to break tests in a documentation PR :))
References are searched using
grep -n -r -P '(?<!``)`[a-zA-Z0-9._"]+`(?!``)' hikari/
A bulk of the references found are migrated using variations of
fd . hikari/ -x sd \
'`(ADMINISTRATOR)`'
'[hikari.permissions.Permissions.$1][]'
{};
References that are readily migratable are search using
rg '`hikari\.[a-zA-Z0-9._]+`
Such references are migrated with
fd . hikari/ -x sd '`(hikari\.[a-zA-Z0-9._]+)`' '[$1][]' hikari/
* Migrate stdlib reference to MkDocs * Address broken `.` references * Housekeeping: Backtick on unmigrated references * Correct additional Hikari references * Inline dunder to prevent incorrect bolding
* Remove mention of deprecated GuildStoreChannel Deprecated and removed in hikari-py#1092 * Minor spellchecking * MANAGE_INVITES is now CREATE_INSTANT_INVITES https://discord.com/developers/docs/resources/guild#add-guild-member * Migrate to MANAGE_GUILD_EXPRESSIONS * Expand GUILDER_MEMBERS intent * Expand `undefined` * Housekeeping: New line to appease formatter * Expand and beautify `hikari.undefined`'s docs * stdlib reference linking * Change "Bot" tab reference to Discord's Dev Portal This should be a good kickstarter. Should. * Add missing `position` arg in `add_role()` * Make `Intents`'s docs a bit more helpful * Address MkDocs' build warning * Housekeeping: Appease `flake8` * Migrate leftover backtick reference * Change MANAGE_PERMISSIONS to MANAGE_ROLES This could be verified by letting the bot have Manage Permissions permission in a channel and check that channel's overwrites. * Expand Webhook.token according to scope * More stdlib migration * Expand aliases * Migrate leftover MANAGE_INVITES * Expand Flag's reference * Typo fix * Expand BasicAuthHeader * Resolve READ_MESSAGE to VIEW_CHANNEL * Expand internal Enum * Expand MEMBERS to CacheComponent.MEMBERS * Bump MkDocs dependencies * Make cross-references inline code
Summary
Reimplement the documentation in mkdocs material.
Deployments:
Github PagesoutdatedI 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
Docstrings were not adjusted for the new admonishment stylesPR branch needs to be removed from github action triggers (or pages action removed entirely)Pages action was removedThese 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
arcinto the readme.