Getting docs to a good starting point

[ajfriend]

Here's a starting point for the docs (builds without failures due to incorrectly formatted docstrings).

Definitely more work to do. I'm not sure if we should just land this now and iterate on the docs (potentially in an async fashion), or if we should continue to polish up this PR.

You can see the docs built from this PR at: https://ajfriend.github.io/h3-py (I've been using this as sort of a docs staging area)

An older, very incomplete version is currently live at https://uber.github.io/h3-py

[ajfriend]

Also, @kylebarron, maybe there's some overlap with your #194 in terms of making sure the docstrings are properly formatted and match up with the type stubs.

[codecov]

Codecov Report

Merging #197 (a156e17) into master (f5053e3) will not change coverage.
The diff coverage is n/a.

❗ Current head a156e17 differs from pull request most recent head 1ef1c78. Consider uploading reports for the commit 1ef1c78 to get more accurate results

@@            Coverage Diff            @@
##            master      #197   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files            9         9           
  Lines          213       213           
=========================================
  Hits           213       213           

Impacted Files	Coverage Δ
src/h3/api/_api_template.py	100.00% <ø> (ø)

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update f5053e3...1ef1c78. Read the comment docs.

[ajfriend]

Also, there is some nice functionality with JupyerBook that lets you launch notebook examples directly into a live cloud service, which would be awesome for the examples repo.

For example, check out the "Launch Notebook" button on this page: https://python.quantecon.org/geom_series.html

[ajfriend]

Another idea: Juypter Book lets you output to multiple formats. It might be nice to publish a PDF version of the docs with each h3-py release. Definitely nice for historical documentation purposes.

[isaacbrodsky]

I wonder if there's a way to include this on the h3geo.org domain too - maybe a subdomain (like py.h3geo.org?)

[ajfriend]

That'd be nice!

[kylebarron]

• Cool! I've never used Jupyter Book for docs before (I've only used mkdocs, example)
• How does docstring generation work? Is it interpreting the docstring as Markdown? Why do you need double `` instead of a single `?
• Judging from .. code-block:: text ... this is using sphinx to generate the api docs? So it's kinda a mix of RST for docstrings, Markdown for prose?
• I'd suggest checking out pydocstyle for CI if you plan to autogenerate docs from docstrings. Might make it simpler to verify docstrings are as expected (but I haven't used it myself).
• Re types: I don't really understand the intersection between RST/sphinx/jupyter book in this docs setup, but I've gotten type inference to work in Sphinx docs generation before (3 years ago 😄) via https://github.com/agronholm/sphinx-autodoc-typehints. But I'm not sure if that works at all via stub files, or just using in-code type hints, and might be irrelevant if you're not using autodoc.

[kylebarron]

Oh I see you are using autodoc...

[kylebarron]

Took a quick look; I checked out your repo and added the sphinx_autodoc_typehints dependency. It does work out of the box with in-line types, e.g.

    def versions() -> Dict[str, str]:

shows

But

1. I don't have the impression that you'd be interested in in-line types, since I think this still supports 2.7.
2. It could be hard to get the generic typing to work for in-line types (though I'm not sure it works for the type stubs anyways), and the typehints plugin complains with WARNING: Cannot treat a function defined as a local function: "h3.versions" (use @functools.wraps. I think this is because of the API factory function. https://github.com/agronholm/sphinx-autodoc-typehints/issues/123
3. Type stubs aren't supported. https://github.com/agronholm/sphinx-autodoc-typehints/issues/161

[ajfriend]

Thanks @kylebarron

• How does docstring generation work? Is it interpreting the docstring as Markdown? Why do you need double `` instead of a single `?
• Judging from .. code-block:: text ... this is using sphinx to generate the api docs? So it's kinda a mix of RST for docstrings, Markdown for prose?

JupyterBook uses the MyST Parser so that you can use markdown instead of RST, which I'll do almost anything to avoid :)
It's a fairly complete replacement, but with one major exception being docstrings, which is why you need those `` (in the docstrings, but not in the website markdown files).

• I'd suggest checking out pydocstyle for CI if you plan to autogenerate docs from docstrings. Might make it simpler to verify docstrings are as expected (but I haven't used it myself).

I'll check it out, thanks!

• Re types: I don't really understand the intersection between RST/sphinx/jupyter book in this docs setup, but I've gotten type inference to work in Sphinx docs generation before (3 years ago 😄) via https://github.com/agronholm/sphinx-autodoc-typehints. But I'm not sure if that works at all via stub files, or just using in-code type hints, and might be irrelevant if you're not using autodoc.

Since this doesn't seem to be straightforward, let's defer the typing stuff (at least for the docs) to later.

1. I don't have the impression that you'd be interested in in-line types, since I think this still supports 2.7.

And I don't think we're ready to drop 2.7 just yet, as there is still a large user base. (I think)