Document our public API

[gsnedders]

For semver to make any sense, we really need to actually define what our public API is. We probably want to do this both through documentation and through the de-facto Python standard of underscore-prefixing (though that will likely break stuff again, le sight, but if people are using the private API they'll likely complain when we do break it in some 1.x release).

[spacekitteh]

Is this being worked on at all?

[gsnedders]

@spacekitteh Pretty much no; I basically got burnt out from a bunch of OSS stuff I was doing in my spare time, this included, so pretty much nothing has happened since the last release.

[spacekitteh]

Sorry to hear :(

[gsnedders]

FWIW, I have two separate transatlantic trips next month, so I'm hopeful of getting something done then because flights to the West Coast are just Too Damned Long to not run out of things to do.

Half the problem with documenting the API is the fact that some of the arcane parts I don't really know what the API even is. There's basically two halves: the half that almost anyone could write (realistically, this extends little beyond what's included in html5lib.__all__ as well as the treewalker and filter API), and then there's the other half (primarily the treebuilder API) which I couldn't write.

If anyone wants to help with the former, absolutely do! I can't promise I'll be great at dealing with PRs, though, for the reasons above… :\ Even if I don't get back to you in a timely manner, there's every chance your work will end up getting included when I do start working on it again.

[willkg]

I think the punch list is something like this:

1. Go through the README and docs/movingparts.rst and verifying examples work and cover only publicly supported API bits
2. Figure out why treebuilders is listed twice in subpackages with different things in it
3. Go through html5lib.constants and document publicly supported API bits
4. Go through html5lib.html5parser and document publicly supported API bits
5. Go through html5lib.serializer and document publicly supported API bits
6. Go through html5lib.filters and document publicly supported API bits
7. Go through html5lib.treebuilders and document publicly supported API bits
8. Go through html5lib.treewalkers and document publicly supported API bits
9. Go through html5lib.treeadapters and document publicly supported API bits

I'll go through these one at a time, do a first pass, and set up a PR.

[willkg]

The work here finished except for any post-review work to do. Just waiting on @gsnedders to review PR #386.