Include README.md in Sphinx docs

[hickford]

Another step for #41

Example output: https://langcodes-hickford.readthedocs.io/en/sphinx/ including API docs https://langcodes-hickford.readthedocs.io/en/sphinx/source/langcodes.html.

[rspeer]

It's looking better to have the README in there, as it's the documentation I'd actually want people to read.

Could you exclude the not-for-public-consumption modules from the documentation? build_data, data_dicts, language_lists, registry_parser, and tag_parser aren't really a public API (except that users might want to catch langcodes.tag_parser.LanguageTagError).

The table of contents (containing only "langcodes" and "langcodes package") is extraneous and should be excluded.

Also, there should be more whitespace between function documentation. It currently looks like the vertical space between functions is less than the vertical space between lines of text.

[rspeer]

More issues I'm noticing:

• Docstrings are mostly being interpreted as RST instead of Markdown (notice the literal underscores that are coming through, and the monospace that's turning into italics
• Constants are being documented, unhelpfully, by the module-level autodoc
• The code examples end up with a stripey look as each one ends up in a separate text box with a background, and the text box only holds like 60 columns of text, requiring horizontal scrolling
• Type annotations are not formatted well

I hope it's okay that I'm being picky about this. I put some effort into making the README sufficiently readable documentation for the package, and I think Sphinx is not doing as well so far.

[hickford]

Of course!

Docstrings are mostly being interpreted as RST instead of Markdown

This looks to be blocked by executablebooks/MyST-Parser#228 . Will return to this in future.

[georgkrause]

@hickford Are you still interested in working on this?