Resolve docstring errors and transition to MkDocs

[MitchellAcoustics]

Transitioning to mkdocs for documentation.

At current stage 7d116d0, the mkdocs is configured, and some pages and docstrings have been converted.

Ongoing work is to continue converting docstrings, then integrate jupyter notebooks, then reexamine the layout and organisation of the docs

[MitchellAcoustics]

Complete conversion of the docs and doc strings to (1) Google-style doc strings and (2) Mkdocs / Mkdocs-material.

Most importantly this resolves #32 and #23!

Documentation

I've tried to keep the documentation as close as I can to the last version of python-acoustics. Wherever possible, I've retained the explanations and math expressions. Where possible I've added Args and Returns to the doc strings if they were missing.

I used Mkdocs Material, mkdocstrings, and mkdocs-jupyter. Readthedocs works - can check out the rendered docs page here: https://acoustic-toolbox.readthedocs.io/en/doc-fix/

API Reference

As of c742af7 the navigation is done partly manually. There are separate .md files for each module in which we include a mkdocstrings snippet to automatically generate the API docs from the docstrings:

::: acoustic_toolbox.directivity
    options:
        show_root_heading: false
        show_source: true
        show_docstring_yields: true

This is a useful balance between auto generating the API docs and flexibility of layout. We can add more explanations or links to the .md file, as well as splitting out modules into different pages for their separate classes, etc. I've been thinking of doing this for some of the modules that have lots of code, like signal.py.

But another alternative is mkdocs-api-autonav which can generate the whole thing automatically and add it to the mkdocs.yml nav section with the same structure as the package (i.e. standards go into separate subpages under standards. This would decrease the maintenance, but be a bit less flexible for how we organize the docs page.

I tested this out with the following options:

plugins:
  - api-autonav:
      modules: ['acoustic_toolbox']
      nav_section_title: "API Reference"

and removing all of the api pages from mkdocs.yml nav. This does work quite well and is essentially equivalent to what we currently have. But prevents us from breaking down certain modules into separate pages. Not sure which would be preferred.

Jupyter examples

mkdocs-jupyter works very well for including the Jupyter notebooks as examples. The main hitch is the examples/ folder must be included within docs/ so I've moved them there. I think this is fine though. At the moment, the whole site takes about 25 seconds to build. Without the Jupyter examples, it takes 8 seconds.

Typehinting

I also added some type hinting - again, I tried not to go overboard and only include type hints where the types were previously stated or were obvious, although some of these may still need to change. This has two consequences:

1. Some type hints are still missing and we should add them as we go through.
2. We do get quite a few type check errors/warnings. As much as possible, if a type error was raised, I didn't include a new type hint, but if one was previously included and it now raises a warning I've left it in for us to address.

That means there are quite a warnings raised by mypy / the IDE type checker which may seem annoying. I think it's better for us to keep these in and be aware of them. It's a good starting point to identify things to address. Running mkdocs build / mkdocs serve currently throws a lot of warnings about missing type hints - this doesn't affect the docs build it might just be annoying, but again I think it's better to leave this and slowly work our way through to resolve them.

There's some inconsistency in the type used for numpy ndarrays - np.ndarray vs NDArray[np.float64]. From what I can tell, NDArray is preferred since it's more explicit. I think this will all be irrelevant when switching to xarray #36 , which from looking into, I think is a good choice.

[MitchellAcoustics]

@Nitnelav what do you think about the auto api vs slightly manual approach? It could be nice not to have to worry about changing the docs when new modules are added or code is refactored. All we'd have to do is add docstrings and mkdocs-api-autonav will automatically pick them up. We'd remove all of the module .md files from docs (e.g. docs/signal.md) and only have .md pages specifically for actually writing documentation, rather than for documenting the API.

Any preference? I'm pretty happy with either.

API Reference

As of c742af7 the navigation is done partly manually. There are separate .md files for each module in which we include a mkdocstrings snippet to automatically generate the API docs from the docstrings:

::: acoustic_toolbox.directivity
    options:
        show_root_heading: false
        show_source: true
        show_docstring_yields: true

This is a useful balance between auto generating the API docs and flexibility of layout. We can add more explanations or links to the .md file, as well as splitting out modules into different pages for their separate classes, etc. I've been thinking of doing this for some of the modules that have lots of code, like signal.py.

But another alternative is mkdocs-api-autonav which can generate the whole thing automatically and add it to the mkdocs.yml nav section with the same structure as the package (i.e. standards go into separate subpages under standards. This would decrease the maintenance, but be a bit less flexible for how we organize the docs page.

I tested this out with the following options:

plugins:
  - api-autonav:
      modules: ['acoustic_toolbox']
      nav_section_title: "API Reference"

and removing all of the api pages from mkdocs.yml nav. This does work quite well and is essentially equivalent to what we currently have. But prevents us from breaking down certain modules into separate pages. Not sure which would be preferred.

[MitchellAcoustics]

See the other readthedocs version build for how it looks with the autoapi version. Deployed from docs-autoapi branch.

[Nitnelav]

Waow this is some really nice work ! 🎉

I think I prefer having the ability to edit some modules pages if necessary. But I'm happy to let you chose the other way if you wish, considering you've done all the work

Awesome stuff anyway ! 👌

[MitchellAcoustics]

Cool! I'm happy to stick with the current setup (not atonal). I'll go ahead and approve the pull request and test the release.