From 493d1f35b9ccb3e7a3c3f68ec9a73d36c6dc4537 Mon Sep 17 00:00:00 2001 From: Nicolas Tessore Date: Fri, 22 Mar 2024 10:17:55 +0000 Subject: [PATCH] skeleton for docs --- .readthedocs.yml | 13 ++++ README.md | 7 +- docs/.gitignore | 1 + docs/Makefile | 20 ++++++ docs/chealpix.rst | 15 +++++ docs/conf.py | 33 +++++++++ docs/healpix.rst | 62 +++++++++++++++++ docs/index.rst | 19 ++++++ docs/library.rst | 15 +++++ docs/make.bat | 35 ++++++++++ python/reference.txt | 155 ------------------------------------------- setup.cfg | 3 + 12 files changed, 218 insertions(+), 160 deletions(-) create mode 100644 .readthedocs.yml create mode 100644 docs/.gitignore create mode 100644 docs/Makefile create mode 100644 docs/chealpix.rst create mode 100644 docs/conf.py create mode 100644 docs/healpix.rst create mode 100644 docs/index.rst create mode 100644 docs/library.rst create mode 100644 docs/make.bat delete mode 100644 python/reference.txt diff --git a/.readthedocs.yml b/.readthedocs.yml new file mode 100644 index 0000000..eaf0672 --- /dev/null +++ b/.readthedocs.yml @@ -0,0 +1,13 @@ +version: 2 + +build: + os: ubuntu-22.04 + tools: + python: "3.12" + +python: + install: + - method: pip + path: . + extra_requirements: + - docs diff --git a/README.md b/README.md index 2fe0721..af34596 100644 --- a/README.md +++ b/README.md @@ -6,6 +6,8 @@ healpix This package implements a lean set of routines for working with the HEALPix discretisation of the sphere. It supports NSIDE parameters up to 2^29. +The online documentation can be found [here](http://healpix.readthedocs.io). + The C library is based on the *healpix_bare* library, which was released under the 3-clause BSD license, with the following additions: @@ -38,9 +40,6 @@ The Python package consists of two modules: * Random point picking in HEALPix pixels. -For a function reference, run `pydoc healpix` (or `pydoc chealpix`) locally if -you have the package installed, or see the [online reference][pydoc]. - The high-level functions in the `healpix` module can be used more or less interchangeably with functions from the *healpy* package. However, in some cases, compatibility is sacrificed for consistency. @@ -67,5 +66,3 @@ and therefore have minimal memory overhead: >>> >>> # no memory overhead: only the 2G output arrays were used ``` - -[pydoc]: https://github.com/ntessore/healpix/raw/main/python/reference.txt diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 0000000..e35d885 --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1 @@ +_build 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/chealpix.rst b/docs/chealpix.rst new file mode 100644 index 0000000..042e507 --- /dev/null +++ b/docs/chealpix.rst @@ -0,0 +1,15 @@ + +:mod:`chealpix` -- Python bindings +================================== + +.. currentmodule:: chealpix +.. module:: chealpix + +Vectorised Python bindings to the HEALPix C library. + +.. data:: NSIDE_MAX + + Maximum admissible value for the NSIDE parameter. + + If nside > NSIDE_MAX is used, the resulting pixel indices can overflow their + underlying integer type in the C library functions. diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..d0f68a7 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,33 @@ +# Configuration file for the Sphinx documentation builder. +# +# For the full list of built-in configuration values, see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Project information ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information + +from importlib import metadata + +project = 'healpix' +copyright = '2024, Nicolas Tessore' +author = 'Nicolas Tessore' +version = metadata.version(project) +release = version + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +extensions = [ + 'sphinx.ext.autodoc', +] + +templates_path = ['_templates'] +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] + + + +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output + +html_theme = 'furo' +html_static_path = ['_static'] diff --git a/docs/healpix.rst b/docs/healpix.rst new file mode 100644 index 0000000..c9f9788 --- /dev/null +++ b/docs/healpix.rst @@ -0,0 +1,62 @@ + +:mod:`healpix` -- Python module +=============================== + +.. currentmodule:: healpix +.. module:: healpix + +Python module for the HEALPix discretisation of the sphere. + + +Resolution +---------- + +.. autodata:: NSIDE_MAX + +.. function:: nside2npix(nside) + npix2nside(npix) + + Convert between resolution parameter *nside* and number of pixels *npix*. + + +.. function:: nside2order(nside) + order2nside(order) + + Convert between resolution parameter *nside* and HEALPix order *order*. + Requires *nside* to be a power of two. + + +Pixel routines +-------------- + +.. function:: ang2pix(nside, theta, phi, nest=False, lonlat=False) + pix2ang(nside, ipix, nest=False, lonlat=False) + +.. function:: pix2vec(nside, ipix, nest=False) + vec2pix(nside, x, y, z, nest=False) + +.. function:: ang2vec(theta, phi, lonlat=False) + vec2ang(x, y, z, lonlat=False) + +.. function:: ring2nest(nside, ipix) + nest2ring(nside, ipix) + + +Subpixel indexing +----------------- + + +Random point picking +-------------------- + +.. autofunction:: randang +.. autofunction:: randvec + + +Multi-Order Coverage (MOC) +-------------------------- + +.. function:: pix2uniq(order, ipix, nest=False) + uniq2pix(uniq, nest=False) + + Convert pixel indices to or from the UNIQ pixel indexing scheme. diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..9836b84 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,19 @@ + +Welcome to healpix's documentation! +=================================== + +.. toctree:: + :maxdepth: 2 + :caption: Contents + + healpix + chealpix + library + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/docs/library.rst b/docs/library.rst new file mode 100644 index 0000000..f8b80a3 --- /dev/null +++ b/docs/library.rst @@ -0,0 +1,15 @@ +C library +========= + +The C library consists of a header ``healpix.h`` and source ``healpix.c``. The +files have no requirements besides a C99-compatible compiler, and are usually +copied directly into a project. + + +Reference +--------- + +The contents of the ``healpix.h`` header file are reproduced below. + +.. literalinclude:: ../src/healpix.h + :language: c diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..32bb245 --- /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 + +%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.https://www.sphinx-doc.org/ + exit /b 1 +) + +if "%1" == "" goto help + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/python/reference.txt b/python/reference.txt deleted file mode 100644 index 9ee0295..0000000 --- a/python/reference.txt +++ /dev/null @@ -1,155 +0,0 @@ -Help on package healpix: - -NAME - healpix - Python package for HEALPix discretisation of the sphere - -PACKAGE CONTENTS - test (package) - -FUNCTIONS - ang2pix(nside, theta, phi, nest=False, lonlat=False) - - ang2vec(theta, phi, lonlat=False) - - nest2ring(nside, ipix) - - npix2nside(npix) - - nside2npix(nside) - - nside2order(nside) - Return the HEALPix order for a given NSIDE parameter. - - order2nside(order) - Return the NSIDE parameter for a given HEALPix order. - - pix2ang(nside, ipix, nest=False, lonlat=False) - - pix2uniq(order, ipix, nest=False) - Convert RING or NEST to UNIQ pixel scheme. - - Returns a pixel index in the UNIQ scheme for each pair of HEALPix - order `order` and pixel index `ipix` in the RING scheme (if `nest` - is false, the default) or the NEST scheme (if `nest` is true). - - pix2vec(nside, ipix, nest=False) - - randang(nside, ipix, nest=False, lonlat=False, rng=None) - Sample random spherical coordinates from the given HEALPix pixels. - - This function produces one pair of random spherical coordinates from each - HEALPix pixel listed in `ipix`, which can be scalar or array-like. The - indices use the `nside` resolution parameter and either the RING scheme - (if `nest` is false, the default) or the NEST scheme (if `nest` is true). - - Returns either a tuple `theta, phi` of mathematical coordinates in radians - if `lonlat` is False (the default), or a tuple `lon, lat` of longitude and - latitude in degrees if `lonlat` is True. The output is of the same shape - as the input. - - An optional numpy random number generator can be provided using `rng`; - otherwise, a new numpy.random.default_rng() is used. - - randvec(nside, ipix, nest=False, rng=None) - Sample random unit vectors from the given HEALPix pixels. - - This function produces one random unit vector from each HEALPix pixel - listed in `ipix`, which can be scalar or array-like. The pixel indices use - the `nside` resolution parameter and either the RING scheme (if `nest` is - false, the default) or the NEST scheme (if `nest` is true). - - Returns a tuple `x, y, z` of normalised vector components with the same - shape as the input. - - An optional numpy random number generator can be provided using `rng`; - otherwise, a new numpy.random.default_rng() is used. - - ring2nest(nside, ipix) - - uniq2pix(uniq, nest=False) - Convert from UNIQ to RING or NEST pixel scheme. - - Returns a tuple `order, ipix` of HEALPix orders and pixel indices in - the RING scheme (if `nest` is false, the default) or the NEST scheme - (if `nest` is true). - - vec2ang(x, y, z, lonlat=False) - - vec2pix(nside, x, y, z, nest=False) - -DATA - NSIDE_MAX = 536870912 - -VERSION - 2024.1 - - -Help on module chealpix: - -NAME - chealpix - healpix C library interface - -FUNCTIONS - ang2nest(nside, theta, phi, ipix=None, /) - - ang2nest_uv(nside, theta, phi, ipix=None, u=None, v=None, /) - - ang2ring(nside, theta, phi, ipix=None, /) - - ang2ring_uv(nside, theta, phi, ipix=None, u=None, v=None, /) - - ang2vec(nside, theta, phi, x=None, y=None, z=None, /) - - nest2ang(nside, ipix, theta=None, phi=None, /) - - nest2ang_uv(nside, ipix, u, v, theta=None, phi=None, /) - - nest2ring(nside, ipnest, ipring=None, /) - - nest2uniq(order, ipix, uniq=None, /) - - nest2vec(nside, ipix, x=None, y=None, z=None, /) - - nest2vec_uv(nside, ipix, u, v, x=None, y=None, z=None, /) - - npix2nside(npix, /) - - nside2npix(nside, /) - - nside2order(nside, /) - - order2nside(order, /) - - ring2ang(nside, ipix, theta=None, phi=None, /) - - ring2ang_uv(nside, ipix, u, v, theta=None, phi=None, /) - - ring2nest(nside, ipring, ipnest=None, /) - - ring2uniq(order, ipix, uniq=None, /) - - ring2vec(nside, ipix, x=None, y=None, z=None, /) - - ring2vec_uv(nside, ipix, u, v, x=None, y=None, z=None, /) - - uniq2nest(uniq, order=None, ipix=None, /) - - uniq2ring(uniq, order=None, ipix=None, /) - - vec2ang(nside, x, y, z, theta=None, phi=None, /) - - vec2nest(nside, x, y, z, ipix=None, /) - - vec2nest_uv(nside, x, y, z, ipix=None, u=None, v=None, /) - - vec2ring(nside, x, y, z, ipix=None, /) - - vec2ring_uv(nside, x, y, z, ipix=None, u=None, v=None, /) - -DATA - NSIDE_MAX = 536870912 - -VERSION - 2024.1 - - diff --git a/setup.cfg b/setup.cfg index 55c0157..31365e4 100644 --- a/setup.cfg +++ b/setup.cfg @@ -28,3 +28,6 @@ install_requires = [options.extras_require] test = pytest +docs = + sphinx + furo