diff --git a/README.md b/README.md index 8f6b2f2..6aa53dc 100644 --- a/README.md +++ b/README.md @@ -1,27 +1,44 @@ # cuda-histogram + + [![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). - +The package is under active development at the moment. [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/ diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..d4bb2cb --- /dev/null +++ b/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) diff --git a/docs/api/cuda_histogram.hist_tools.rst b/docs/api/cuda_histogram.hist_tools.rst new file mode 100644 index 0000000..1ba2d3c --- /dev/null +++ b/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: diff --git a/docs/api/cuda_histogram.plot.rst b/docs/api/cuda_histogram.plot.rst new file mode 100644 index 0000000..bc175e5 --- /dev/null +++ b/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: diff --git a/docs/api/cuda_histogram.rst b/docs/api/cuda_histogram.rst new file mode 100644 index 0000000..65f032a --- /dev/null +++ b/docs/api/cuda_histogram.rst @@ -0,0 +1,11 @@ +cuda_histogram package +====================== + +Submodules +---------- + +.. toctree:: + :maxdepth: 3 + + cuda_histogram.hist_tools + cuda_histogram.plot diff --git a/docs/api/modules.rst b/docs/api/modules.rst new file mode 100644 index 0000000..58754f5 --- /dev/null +++ b/docs/api/modules.rst @@ -0,0 +1,7 @@ +cuda-histogram +============== + +.. toctree:: + :maxdepth: 4 + + cuda_histogram diff --git a/docs/changelog.md b/docs/changelog.md new file mode 100644 index 0000000..fcf9f71 --- /dev/null +++ b/docs/changelog.md @@ -0,0 +1,5 @@ +# CHANGELOG + +## Version 0.0.1 + +- Initial release - a working prototype diff --git a/docs/index.md b/docs/index.md index ada5061..cf43225 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,4 +1,4 @@ -# cuda-histogram +# Overview ```{toctree} :maxdepth: 2 @@ -10,6 +10,56 @@ :start-after: ``` +## 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` diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..922152e --- /dev/null +++ b/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 diff --git a/src/cuda_histogram/__init__.py b/src/cuda_histogram/__init__.py index 0cb09cf..e0e1068 100644 --- a/src/cuda_histogram/__init__.py +++ b/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 `__ (deprecated), -`boost-histogram `__ (in development), -`physt `__, and built-in numpy -`histogram `__ utilities. +""" +`cuda-histogram` is a histogram filling, transformation, and plotting package for GPUs. +The package follows `UHI `__ and keeps its API similar to +`boost-histogram `__ +`and hist `__. """ from __future__ import annotations