hikari-py/hikari

Switch to `pdoc` and update theme

Closed this issue · 2 comments

davfsa commented

We should switch to pdoc with a new template to make the documentation easier to read and navigate. This should be done before #410 as the way pdoc outputs the HTML is a nicer and more compact format to allow for different version documentation.

Due to the huge scope of this, I will create a branch called feature/pdoc where progress will be made, which will later be merged into master once everything is ready.

pdoc

  • Ensure everything renders correctly
    • pdoc uses a more strict numpy docstring style, so some things we are currently doing wont render nicecly anymore
      • See also section should only consist of links, no other text
  • Properties docstrings should not include a Returns section
  • Fix all the warnings printed (mitmproxy/pdoc#307) [Python bug, so nothing we can do about it. Hopefully will be fixed in the future]
  • Ensure in-project linking works (relates to above)
  • object.inv output

Theme

Still not decided. I have recently become a fan of rust projects documentation, as well as the nice usage of the sidebar in rustbook, so will probably take inspiration from there

Both lists are not complete and can be edited to add more points as more issues are found or changes are to be made

FasterSpeeding commented

I'ma just drop this script here cause this is a pretty nice way to get an easy to consume search json index on v8 pdoc https://gist.github.com/FasterSpeeding/19a6d3f44cdd0a1f3b2437a8c5eef07a (the result is the same as v7's search.json which has since been replaced by search.js which too specifically targets browsers making it useless for 3rd party stuff)

  • 👍1
davfsa commented

Technically closed by #856, but will keep open till the branch is merged into master