Add usage example to docs

[scottstanie]

WIP, I need to check how to locally build sphinx.

I'm also open to "that is not at all how I'd introduce the usage" if you have different opinions.

But when trying to build on linux, I got the error

$ make html
Extension error (sphinx.ext.autosummary):
Handler <function process_generate_options at 0x7fbadc75b4c0> for event 'builder-inited' threw an exception (exception: no module named tophu.TiledPartition)
make: *** [html] Error 2

and on mac I got the classic

Traceback (most recent call last):
  File "/Users/staniewi/miniconda3/envs/mapping/lib/python3.10/site-packages/sphinx/config.py", line 347, in eval_config_file
    exec(code, namespace)
  File "/Users/staniewi/repos/tophu/docs/source/conf.py", line 3, in <module>
    import tophu
  File "/Users/staniewi/repos/tophu/src/tophu/__init__.py", line 5, in <module>
    from ._multiscale import *
  File "/Users/staniewi/repos/tophu/src/tophu/_multiscale.py", line 17, in <module>
    from ._unwrap import UnwrapCallback
  File "/Users/staniewi/repos/tophu/src/tophu/_unwrap.py", line 10, in <module>
    import isce3
  File "/Users/staniewi/repos/isce3/install/packages/isce3/__init__.py", line 2, in <module>
    from .ext import extisce3
  File "/Users/staniewi/repos/isce3/install/packages/isce3/ext/__init__.py", line 3, in <module>
    from . import isce3 as extisce3
ImportError: dlopen(/Users/staniewi/repos/isce3/install/packages/isce3/ext/isce3.cpython-310-darwin.so, 0x0002): Library not loaded: @rpath/libisce3.0.dylib
  Referenced from: <9D92F2C0-7221-38F1-86A3-D88793E67774> /Users/staniewi/repos/isce3/install/packages/isce3/ext/isce3.cpython-310-darwin.so
  Reason: tried: '/Users/staniewi/miniconda3/envs/mapping/lib/libisce3.0.dylib' (no such file), '/System/Volumes/Preboot/Cryptexes/OS/Users/staniewi/miniconda3/envs/mapping/lib/libisce3.0.dylib' (no such file), '/Users/staniewi/miniconda3/envs/mapping/lib/libisce3.0.dylib' (no such file), '/System/Volumes/Preboot/Cryptexes/OS/Users/staniewi/miniconda3/envs/mapping/lib/libisce3.0.dylib' (no such file), '/Users/staniewi/miniconda3/envs/mapping/bin/../lib/libisce3.0.dylib' (no such file), '/Users/staniewi/miniconda3/envs/mapping/bin/../lib/libisce3.0.dylib' (no such file), '/usr/local/lib/libisce3.0.dylib' (no such file), '/usr/lib/libisce3.0.dylib' (no such file, not in dyld cache)

(despite the fact that import isce3 works fine in a normal interpreter)

[codecov]

Codecov Report

Merging #37 (a5c57e0) into main (66df96f) will decrease coverage by 0.01%.
Report is 2 commits behind head on main.
The diff coverage is n/a.

@@            Coverage Diff             @@
##             main      #37      +/-   ##
==========================================
- Coverage   97.86%   97.86%   -0.01%     
==========================================
  Files           9        9              
  Lines         797      796       -1     
==========================================
- Hits          780      779       -1     
  Misses         17       17              

see 2 files with indirect coverage changes

📣 We’re building smart automated test selection to slash your CI/CD build times. Learn more

[gmgunter]

But when trying to build on linux, I got the error

$ make html
Extension error (sphinx.ext.autosummary):
Handler <function process_generate_options at 0x7fbadc75b4c0> for event 'builder-inited' >threw an exception (exception: no module named tophu.TiledPartition)
make: *** [html] Error 2

An annoying thing about sphinx.ext.autosummary is that it litters the source tree with auto-generated stub files that you have to know to clean up later on if you want a fresh build. I think that's what happened here. You probably tried to build the docs a while back when tophu.TiledPartition still existed and the stub files for it are still sitting in your source tree.

The contents of docs/source/api are all auto-generated and not tracked by git. If you clean out that directory and try to build the docs again, I bet the issue will be resolved. I just tried it with a fresh clone of your branch and had no problems.

It'd be nice if I taught make clean to delete this directory -- sorry for the inconvenience.

Can't help you with the macOS issue 😝

[gmgunter]

Thanks for improving the docs! Few minor stylistic gripes below