Add docs

[LiamPattinson]

Updates docstrings and adds HTML documentation with Sphinx.

• Docstrings rewritten to use NumPy doc style
• Updates type-hints throughout, as these are used by the Sphinx plug-in sphinx_autodoc_typehints.
• Adds Sphinx files in the docs/ directory (mostly boilerplate, though conf.py and index.rst may need to be edited from time to time)

The majority of this was completed by @ZedThree -- I've simply merged it with the latest main and checked for bugs.

Docs can be built locally by the following steps:

pip install .[docs]  # Get the documentation dependencies
cd docs
make html

You can then check them by navigating to file:///path/to/simplesimdb/docs/_build/html/index.html in your browser.

@mwiesenberger To set up auto-publishing on readthedocs, you'll have to follow the tutorial from here. I'd recommend setting it to build pull requests, but otherwise the default set up should be fine.

[mwiesenberger]

Hi, I finally found some time to look into this and play around with it. I have some requests that I tried unsuccessfully to figure out myself so I would appreciate if you with more experience can get it to work

[mwiesenberger]

This should copy the corresponding line in ../LICENSE
copyright = "(c) 2021 Technical University of Denmark"

[LiamPattinson]

I've corrected this in 481bfc2. The "(c)" wasn't needed, as one is added automatically in the docs.

[mwiesenberger]

Perfect

[mwiesenberger]

I am not sure what the two files in _templates bring to the table or where they come from? When I run sphinx-quickstart they are not generated, so do they somehow overwrite the default behaviour?

[ZedThree]

Without these custom templates, Sphinx doesn't actually have a way of automatically and recursively generating all the docs. These versions are just modified from the default templates to do that recursive autogeneration.

[LiamPattinson]

They're used by the sphinx.ext.autosummary plugin to automate the generation of module and class documentation. The autodoc plugin is used to automate documentation generation on a per-module/per-class/per-function/etc basis, and autosummary is used to generalise autodoc over all modules/classes/functions in a project.

I think these files were simply copied across from another project. Once you've written documentation for one Python project, it makes a lot of sense to just copy all the boilerplate over to the next, but sometimes you end up bringing over things that aren't strictly necessary.

With the changes I've made I don't think the module template will be needed anymore, so I can delete that if you'd like. Alternatively, it might be worth keeping around just in case the project expands at a later date.

The class template is needed in order for the documentation for Manager and Repeater to be created successfully. If you exclude it, the class itself gets documented but none of its methods do.

[mwiesenberger]

Without these custom templates, Sphinx doesn't actually have a way of automatically and recursively generating all the docs

Hmm why not use

.. automodule:: simplesimdb
    :members:
    :undoc-members:
    :show-inheritance:

For me that creates all classes and Members even without the files in _templates

[mwiesenberger]

I compared custom-class-template.rst to sphinx's default /autosummary/class.rst and the only difference is the addition of

:members:
:undoc-members:
:show-inheritance:

The module custom-module-template.rst compared to sphinx's default /autosummary/module.rsttemplate includes

:toctree

at a couple of places. I think I am ok with just using Sphinx default behaviour for now, if you remove the two _template files for me and include the above automodule for me I can accept the pull request and then play around a bit with the documentation from there and put it onto readthedocs

[mwiesenberger]

I see that you copied a passage of the README.md file here, but I would rather that the README is copied verbatim after the toctree. It should be possible since myst_nb is included as an extension but I couldn't get it to work myself

[LiamPattinson]

I honestly wasn't aware that this was even a possibility, but I've got it working in f169a24. I'll have to remember this trick for my future projects!

[mwiesenberger]

Glad I could point out something useful. Looks good now

[mwiesenberger]

Can "version" be used in the html_title since the full "1.1.2.dev5+gd676620" looks a bit ugly

[LiamPattinson]

I've made the change in 1887a1b. A downside of this is that there won't be any way to tell if a particular version of the docs have been built from the latest release or a mid-development commit, but it's unlikely that users will stumble onto these development builds anyway.

[mwiesenberger]

For me the important thing is also to see how it can be done and you showed an easy and elegant solution that I can play around with in the future, should it become an issue

[mwiesenberger]

I am not entirely sure about the purpose of this file, in my mind the simple thing would be to just include the simplesimdb module in index.rst somehow, or even better have the Reference to the two classes Manager and Repeater go directly on the main page. The "API Reference" just creates another level of indirection to click through...

[LiamPattinson]

It took some experimentation, but I was able to achieve this in 9ceab46. It looks like the general layout of the docs had been copied across from another Python project that made use of many more modules, and in that case the indirection may have made more sense to avoid cluttering the main page.

[mwiesenberger]

Perfect, yes this is what I wanted, I think from here I can figure out how to do more elaborate things in sphinx should it be necessary

[mwiesenberger]

Do I understand this correctly that it will use the requirements in the [docs] group of pyproject.toml?

[LiamPattinson]

That's right, it's just a way to avoid repeating our list of documentation dependencies.

[mwiesenberger]

Nice