docs: initial documentation infrastructure (#12)

README.md

@@ -1,27 +1,44 @@
 # cuda-histogram
 
+<!-- SPHINX-START -->
+
 [![Actions Status][actions-badge]][actions-link]
 [![Documentation Status][rtd-badge]][rtd-link]
+[![pre-commit.ci status][pre-commit-badge]][pre-commit-link]
+[![codecov percentage][codecov-badge]][codecov-link]
+[![GitHub Discussion][github-discussions-badge]][github-discussions-link]
 
-[![PyPI version][pypi-version]][pypi-link]
-[![Conda-Forge][conda-badge]][conda-link]
 [![PyPI platforms][pypi-platforms]][pypi-link]
+[![PyPI version][pypi-version]][pypi-link]
+[![Conda latest release][conda-version]][conda-link]
+[![LICENSE][license-badge]][license-link] [![Scikit-HEP][sk-badge]][sk-link]
 
-[![GitHub Discussion][github-discussions-badge]][github-discussions-link]
+`cuda-histogram` is a histogram filling, transformation, and plotting package
+for GPUs. The package follows [UHI](https://uhi.readthedocs.io) and keeps its
+API similar to [boost-histogram](https://github.com/scikit-hep/boost-histogram)
+and [hist](https://github.com/scikit-hep/hist).
 
-<!-- SPHINX-START -->
+The package is under active development at the moment.
 
 <!-- prettier-ignore-start -->
 [actions-badge]:            https://github.com/Saransh-cpp/cuda-histogram/workflows/CI/badge.svg
 [actions-link]:             https://github.com/Saransh-cpp/cuda-histogram/actions
-[conda-badge]:              https://img.shields.io/conda/vn/conda-forge/cuda-histogram
-[conda-link]:               https://github.com/conda-forge/cuda-histogram-feedstock
+[codecov-badge]:            https://codecov.io/gh/Saransh-cpp/cuda-histogram/branch/main/graph/badge.svg?token=YBv60ueORQ
+[codecov-link]:             https://codecov.io/gh/Saransh-cpp/cuda-histogram
+[conda-version]:            https://img.shields.io/conda/vn/Saransh-cpp/cuda-histogram.svg
+[conda-link]:               https://github.com/Saransh-cpp/cuda-histogram
 [github-discussions-badge]: https://img.shields.io/static/v1?label=Discussions&message=Ask&color=blue&logo=github
 [github-discussions-link]:  https://github.com/Saransh-cpp/cuda-histogram/discussions
+[license-badge]:            https://img.shields.io/badge/License-BSD_3--Clause-blue.svg
+[license-link]:             https://opensource.org/licenses/BSD-3-Clause
+[pre-commit-badge]:         https://results.pre-commit.ci/badge/github/Saransh-cpp/cuda-histogram/main.svg
+[pre-commit-link]:          https://results.pre-commit.ci/repo/github/Saransh-cpp/cuda-histogram
 [pypi-link]:                https://pypi.org/project/cuda-histogram/
 [pypi-platforms]:           https://img.shields.io/pypi/pyversions/cuda-histogram
 [pypi-version]:             https://img.shields.io/pypi/v/cuda-histogram
 [rtd-badge]:                https://readthedocs.org/projects/cuda-histogram/badge/?version=latest
 [rtd-link]:                 https://cuda-histogram.readthedocs.io/en/latest/?badge=latest
+[sk-badge]:                 https://scikit-hep.org/assets/images/Scikit--HEP-Project-blue.svg
+[sk-link]:                  https://scikit-hep.org/
 
 <!-- prettier-ignore-end -->

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/api/cuda_histogram.hist_tools.rst

@@ -0,0 +1,8 @@
+cuda_histogram.hist_tools module
+================================
+
+.. automodule:: cuda_histogram.hist_tools
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :private-members:

docs/api/cuda_histogram.plot.rst

@@ -0,0 +1,8 @@
+cuda_histogram.plot module
+==========================
+
+.. automodule:: cuda_histogram.plot
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :private-members:

docs/api/cuda_histogram.rst

@@ -0,0 +1,11 @@
+cuda_histogram package
+======================
+
+Submodules
+----------
+
+.. toctree::
+   :maxdepth: 3
+
+   cuda_histogram.hist_tools
+   cuda_histogram.plot

docs/api/modules.rst

@@ -0,0 +1,7 @@
+cuda-histogram
+==============
+
+.. toctree::
+   :maxdepth: 4
+
+   cuda_histogram

docs/changelog.md

@@ -0,0 +1,5 @@
+# CHANGELOG
+
+## Version 0.0.1
+
+- Initial release - a working prototype

docs/index.md

@@ -1,4 +1,4 @@
-# cuda-histogram
+# Overview
 
 ```{toctree}
 :maxdepth: 2
@@ -10,6 +10,56 @@
 :start-after: <!-- SPHINX-START -->
 ```
 
+## Installation
+
+cuda-histogram is available on [PyPI](https://pypi.org/project/cuda-histogram/)
+as well as on [conda](https://anaconda.org/conda-forge/cuda-histogram). The
+library can be installed using `pip` -
+
+```{code-block}
+
+pip install cuda-histogram
+
+```
+
+or using `conda` -
+
+```{code-block}
+
+conda install -c conda-forge cuda-histogram
+
+```
+
+## Changes in cuda-histogram's API
+
+The `changelog` file describes the changes in `cuda-histogram`'s API and usage
+introduced in every new version.
+
+```{toctree}
+:maxdepth: 3
+
+changelog
+```
+
+## Getting help
+
+- `cuda-histogram`'s code is hosted on
+  [GitHub](https://github.com/Saransh-cpp/cuda-histogram).
+- If something is not working the way it should, or if you want to request a new
+  feature, create a new
+  [issue](https://github.com/Saransh-cpp/cuda-histogram/issues) on GitHub.
+- To discuss something related to `cuda-histogram`, use the
+  [discussions](https://github.com/Saransh-cpp/cuda-histogram/discussions/) tab
+  on GitHub.
+
+## API reference
+
+```{toctree}
+:maxdepth: 4
+
+api/modules.rst
+```
+
 ## Indices and tables
 
 - {ref}`genindex`

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

src/cuda_histogram/__init__.py

@@ -1,14 +1,9 @@
-"""Histogramming tools
-
-`cuda-histogram` is a histogram filling, transformation, and plotting sub-package, utilizing
-numpy arrays for storage and matplotlib plotting routines for visualization.
-
-Features found in this package are similar to those found in
-packages such as `histbook <https://github.com/scikit-hep/histbook>`__ (deprecated),
-`boost-histogram <https://github.com/scikit-hep/boost-histogram>`__ (in development),
-`physt <https://github.com/scikit-hep/boost-histogram>`__, and built-in numpy
-`histogram <https://docs.scipy.org/doc/numpy/reference/generated/numpy.histogram.html>`__ utilities.
+"""
+`cuda-histogram` is a histogram filling, transformation, and plotting package for GPUs.
 
+The package follows `UHI <https://uhi.readthedocs.io>`__ and keeps its API similar to
+`boost-histogram <https://github.com/scikit-hep/boost-histogram>`__
+`and hist <https://github.com/scikit-hep/hist>`__.
 """
 
 from __future__ import annotations