Set up Sphinx documentation

[tomwhite]

This is the initial work to set up docs for the project, following discussion in #19.

• Uses Sphinx reStructuredText
• Currently very barebones, but shows the two top-level functions
• Uses the ReadTheDocs theme
• Hosted on GitHub pages at https://pystatgen.github.io/sgkit/ (at least for the moment)
• Docstring style is numpydoc, but Google-style docstrings are supported due to use of sphinx.ext.napoleon
• Xarray types in the documentation are automatically converted to links (using sphinx.ext.intersphinx ). Note that these types must be specified using reST, e.g. :class:`xarray.Dataset`

To generate and view docs locally:

cd docs
make html
open _build/html/index.html

[jeromekelleher]

LGTM. What's the plan for deploying to gh-pages?

[tomwhite]

What's the plan for deploying to gh-pages?

Use a GitHub Action to deploy to the gh-pages branch on every commit to master. I think that's the simplest thing to do until we have our first release and want different versions.

[hammer]

Amazing, thanks @tomwhite!

What are your thoughts on how we could incorporate docs from related packages like sgkit-plink and sgkit-bed?

[tomwhite]

What are your thoughts on how we could incorporate docs from related packages like sgkit-plink and sgkit-bed?

Good question. One option would be to generate self-contained docs for each package, and interlink them using sphinx.ext.intersphinx. Since the IO projects have a very small API, I would prefer to just add their docs as separate pages on the main site. We'd author the reST docs there, and pull in the API definitions by importing the modules in the Sphinx conf file.

[hammer]

@tomwhite do we need a follow up issue for that or is it easy enough to just incorporate into this PR and document for others?

[tomwhite]

I think it needs some extra work, so I've opened #54

[tomwhite]

I fixed a broken link in the generated doc at https://pystatgen.github.io/sgkit/

[tomwhite]

I made changes so that the build will fail if Sphinx documentation warnings are introduced. I've also added a workflow to publish the docs to gh-pages when anything is committed to master (but I can't fully test that until this is merged).

Reviews and suggestions welcome!

[tomwhite]

I've rebased this. Any objections to merging this? It will allow us to press on with writing docs.

[jeromekelleher]

This isn't a blocker on merging, but any particular reason for not making this strict? In my experience people writing docs will make lots of mistakes, and the only way to catch these is to have strict checking on and to verify it as part of CI. Otherwise the docs get cruddy pretty quickly when less experienced developers start contributing.

[tomwhite]

We could enable "nit-picky mode" (-n). I tried doing this, but it generated some errors that will need a bit more work to fix. I've opened https://github.com/pystatgen/sgkit/issues/86

[jeromekelleher]

I think we should merge this ASAP - having some functional docs infrastructure is vital at this point.

[tomwhite]

Thanks for the review @jeromekelleher