Sphinx documentation with numpydocs format

[sbenthall]

This PR introduces a docs/ directory which contains the Sphinx machinery for building documentation.

Sphinx is configured to understand numpydocs formatted docstrings. This is roughly standard across scientific Python software packages, as they "inherit" this style from numpy.

Currently, the documentation is quite sparse.

• It pulls in and presents the README file on its own page
• I've made separate pages for each of the modules within bigbang, and these are automatically documented based on docstrings.

We do not have complete numpydocs style docstrings for all the functionality in the library; this is something we can work towards.

[codecov-commenter]

Codecov Report

Merging #491 (9d7323a) into main (7f0b569) will not change coverage. The diff coverage is n/a.

@@           Coverage Diff           @@
##             main     #491   +/-   ##
=======================================
  Coverage   76.96%   76.96%           
=======================================
  Files          20       20           
  Lines        2830     2830           
=======================================
  Hits         2178     2178           
  Misses        652      652           

Flag	Coverage Δ
unittests	76.96% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

Impacted Files	Coverage Δ
bigbang/archive.py	63.87% <ø> (ø)
bigbang/entity_resolution.py	83.05% <ø> (ø)
bigbang/io.py	85.71% <ø> (ø)
bigbang/utils.py	61.19% <ø> (ø)

---

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 7f0b569...9d7323a. Read the comment docs.

[Christovis]

Fantastic! Thanks a lot for this, it will make live for unfamiliar users so much easier!

Btw. why is it at bigbang-py.readthedocs.io and not bigbang.readthedocs.io, was it already taken?

What do you think about the following content structure?

Introduction

• Motivation
• Goals
• License

Installation

• Python Support
• Basic Installation
• Building From Source

Handbook

• Overview
• Tutorial
• maybe Appendices

Data Access

• Data maintenance, format, ...
• Data Access Permit Application

Reference

• Classes and their modules
• File Handling in BigBang

Release Notes

• 0.0.1
• 0.0.2
• ...

[sbenthall]

Btw. how it is at bigbang-py.readthedocs.io and not bigbang.readthedocs.io, was it already taken?

Yes, see discussion on #412

What do you think about the following content structure?

It's a nice aspirational model.