From 7f400a3a8aa9611923f78a19554584b4b7878220 Mon Sep 17 00:00:00 2001 From: Martin Dyer Date: Wed, 21 Jan 2026 14:09:39 +0000 Subject: [PATCH 1/6] Fetch tags for docs version --- .github/workflows/documentation.yml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml index b1d10fc9..f4b6980e 100644 --- a/.github/workflows/documentation.yml +++ b/.github/workflows/documentation.yml @@ -10,6 +10,8 @@ jobs: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 + with: + fetch-depth: 0 # Fetch all history and tags for setuptools_scm - uses: actions/setup-python@v5 with: python-version: '3.9' From 754d8cef34408025370a7687c0f00babffa84ff7 Mon Sep 17 00:00:00 2001 From: Martin Dyer Date: Wed, 21 Jan 2026 14:12:18 +0000 Subject: [PATCH 2/6] Add log for package version --- docs/conf.py | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index 9336ac94..d0999e82 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -66,14 +66,17 @@ # Try to get version from installed package first from importlib.metadata import version as _version release = _version('hipercam') + print(f"[Sphinx] Using installed package version: {release}") except ImportError: # Fallback to setuptools_scm if package not installed try: from setuptools_scm import get_version release = get_version(root='..', relative_to=__file__) - except (ImportError, LookupError): + print(f"[Sphinx] Using setuptools_scm version: {release}") + except (ImportError, LookupError) as e: # Final fallback to a default version release = "unknown" + print(f"[Sphinx] WARNING: Could not determine version ({e}), using: {release}") # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. From 76789acc6edae02b2e8851fb7a6a178eb97c9811 Mon Sep 17 00:00:00 2001 From: Martin Dyer Date: Wed, 21 Jan 2026 17:11:33 +0000 Subject: [PATCH 3/6] Move from autodoc to autoapi --- .github/workflows/documentation.yml | 5 +- docs/commands.rst | 96 ++++++++++++++--------------- docs/conf.py | 13 +++- 3 files changed, 63 insertions(+), 51 deletions(-) diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml index f4b6980e..e75c3f13 100644 --- a/.github/workflows/documentation.yml +++ b/.github/workflows/documentation.yml @@ -15,10 +15,13 @@ jobs: - uses: actions/setup-python@v5 with: python-version: '3.9' + - name: Install hipercam package + run: | + pip install . - name: Install documentation dependencies run: | pip install --upgrade pip setuptools wheel setuptools_scm - pip install sphinx sphinx_rtd_theme myst_parser numpydoc sphinx-astropy + pip install sphinx sphinx_rtd_theme sphinx-autoapi myst_parser numpydoc sphinx-astropy - name: Sphinx build run: | sphinx-build docs _build diff --git a/docs/commands.rst b/docs/commands.rst index f5d76243..78f46246 100644 --- a/docs/commands.rst +++ b/docs/commands.rst @@ -449,54 +449,54 @@ containing multiple images, stored in a .fits file. ``frame`` refers to a single image from a run as might be extracted using |grab|. These have file extension '.hcm' to distinguish them, although they are also FITS-format files. -.. autofunction:: hipercam.scripts.add -.. autofunction:: hipercam.scripts.averun -.. autofunction:: hipercam.scripts.cadd -.. autofunction:: hipercam.scripts.cdiv -.. autofunction:: hipercam.scripts.cmul -.. autofunction:: hipercam.scripts.combine -.. autofunction:: hipercam.scripts.csub -.. autofunction:: hipercam.scripts.div -.. autofunction:: hipercam.scripts.exploss -.. autofunction:: hipercam.scripts.fits2hcm -.. autofunction:: hipercam.scripts.flagcloud -.. autofunction:: hipercam.scripts.ftargets -.. autofunction:: hipercam.scripts.genred -.. autofunction:: hipercam.scripts.grab -.. autofunction:: hipercam.scripts.hfilter -.. autofunction:: hipercam.scripts.hinfo -.. autofunction:: hipercam.scripts.hist -.. autofunction:: hipercam.scripts.hlog2col -.. autofunction:: hipercam.scripts.hlog2fits -.. autofunction:: hipercam.scripts.hls -.. autofunction:: hipercam.scripts.hplot -.. autofunction:: hipercam.scripts.hpackage -.. autofunction:: hipercam.scripts.joinup -.. autofunction:: hipercam.scripts.ltimes -.. autofunction:: hipercam.scripts.ltrans -.. autofunction:: hipercam.scripts.makebias -.. autofunction:: hipercam.scripts.makedark -.. autofunction:: hipercam.scripts.makeflat -.. autofunction:: hipercam.scripts.makefringe -.. autofunction:: hipercam.scripts.makemovie -.. autofunction:: hipercam.scripts.mstats -.. autofunction:: hipercam.scripts.mul -.. autofunction:: hipercam.scripts.ncal -.. autofunction:: hipercam.scripts.nrtplot -.. autofunction:: hipercam.scripts.pbands -.. autofunction:: hipercam.scripts.plog -.. autofunction:: hipercam.scripts.redanal -.. autofunction:: hipercam.scripts.reduce -.. autofunction:: hipercam.scripts.rtplot -.. autofunction:: hipercam.scripts.rupdate -.. autofunction:: hipercam.scripts.setaper -.. autofunction:: hipercam.scripts.setdefect -.. autofunction:: hipercam.scripts.setfringe -.. autofunction:: hipercam.scripts.shiftadd -.. autofunction:: hipercam.scripts.splice -.. autofunction:: hipercam.scripts.stats -.. autofunction:: hipercam.scripts.sub -.. autofunction:: hipercam.scripts.uls +.. autoapifunction:: hipercam.scripts.add +.. autoapifunction:: hipercam.scripts.averun +.. autoapifunction:: hipercam.scripts.cadd +.. autoapifunction:: hipercam.scripts.cdiv +.. autoapifunction:: hipercam.scripts.cmul +.. autoapifunction:: hipercam.scripts.combine +.. autoapifunction:: hipercam.scripts.csub +.. autoapifunction:: hipercam.scripts.div +.. autoapifunction:: hipercam.scripts.exploss +.. autoapifunction:: hipercam.scripts.fits2hcm +.. autoapifunction:: hipercam.scripts.flagcloud +.. autoapifunction:: hipercam.scripts.ftargets +.. autoapifunction:: hipercam.scripts.genred +.. autoapifunction:: hipercam.scripts.grab +.. autoapifunction:: hipercam.scripts.hfilter +.. autoapifunction:: hipercam.scripts.hinfo +.. autoapifunction:: hipercam.scripts.hist +.. autoapifunction:: hipercam.scripts.hlog2col +.. autoapifunction:: hipercam.scripts.hlog2fits +.. autoapifunction:: hipercam.scripts.hls +.. autoapifunction:: hipercam.scripts.hplot +.. autoapifunction:: hipercam.scripts.hpackage +.. autoapifunction:: hipercam.scripts.joinup +.. autoapifunction:: hipercam.scripts.ltimes +.. autoapifunction:: hipercam.scripts.ltrans +.. autoapifunction:: hipercam.scripts.makebias +.. autoapifunction:: hipercam.scripts.makedark +.. autoapifunction:: hipercam.scripts.makeflat +.. autoapifunction:: hipercam.scripts.makefringe +.. autoapifunction:: hipercam.scripts.makemovie +.. autoapifunction:: hipercam.scripts.mstats +.. autoapifunction:: hipercam.scripts.mul +.. autoapifunction:: hipercam.scripts.ncal +.. autoapifunction:: hipercam.scripts.nrtplot +.. autoapifunction:: hipercam.scripts.pbands +.. autoapifunction:: hipercam.scripts.plog +.. autoapifunction:: hipercam.scripts.redanal +.. autoapifunction:: hipercam.scripts.reduce +.. autoapifunction:: hipercam.scripts.rtplot +.. autoapifunction:: hipercam.scripts.rupdate +.. autoapifunction:: hipercam.scripts.setaper +.. autoapifunction:: hipercam.scripts.setdefect +.. autoapifunction:: hipercam.scripts.setfringe +.. autoapifunction:: hipercam.scripts.shiftadd +.. autoapifunction:: hipercam.scripts.splice +.. autoapifunction:: hipercam.scripts.stats +.. autoapifunction:: hipercam.scripts.sub +.. autoapifunction:: hipercam.scripts.uls .. [#f1] Several other commands (``aligntool``, ``atanalysis``, ``atbytes``, ``calsearch``, ``harchive``, ``hlogger``, ``hmeta``, ``logsearch``, diff --git a/docs/conf.py b/docs/conf.py index d0999e82..12f3c054 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -31,14 +31,23 @@ # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. -extensions = ['sphinx.ext.autodoc', 'sphinx.ext.autosummary', - 'sphinx.ext.imgmath', 'numpydoc'] +extensions = [ + 'sphinx.ext.autodoc', + 'sphinx.ext.autosummary', + 'sphinx.ext.imgmath', + 'numpydoc', + 'autoapi.extension', +] # this needed for numpydoc I think autosummary_generate = True numpydoc_show_class_members = False numpydoc_show_inherited_class_members = False +autoapi_dirs = ['../hipercam'] +autoapi_generate_api_docs = False # Don't auto-generate, we'll write e.g. scripts in commands.rst + + # number figures numfig = True From c5e1e207c6afb7aa7adbf88b49d93bb2c6cf9759 Mon Sep 17 00:00:00 2001 From: Martin Dyer Date: Fri, 23 Jan 2026 11:49:55 +0000 Subject: [PATCH 4/6] Minor fixes for docs warnings --- .github/workflows/documentation.yml | 4 +++- README.rst | 12 +++++------- docs/change_log_1.1.0_1.2.0.rst | 2 +- docs/commands.rst | 2 +- docs/conf.py | 9 ++++----- docs/files.rst | 2 +- docs/index.rst | 4 ++-- docs/installation.rst | 3 +-- docs/makingmovies.rst | 3 +-- docs/phaseII.rst | 3 +-- docs/telescope.rst | 2 +- hipercam/hcam.py | 2 +- hipercam/hlog.py | 4 ++-- hipercam/scripts/aligntool.py | 4 ++-- hipercam/window.py | 4 ++-- 15 files changed, 28 insertions(+), 32 deletions(-) diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml index e75c3f13..4c6da002 100644 --- a/.github/workflows/documentation.yml +++ b/.github/workflows/documentation.yml @@ -15,12 +15,14 @@ jobs: - uses: actions/setup-python@v5 with: python-version: '3.9' + - name: Install build tools + run: | + pip install --upgrade pip setuptools wheel setuptools_scm - name: Install hipercam package run: | pip install . - name: Install documentation dependencies run: | - pip install --upgrade pip setuptools wheel setuptools_scm pip install sphinx sphinx_rtd_theme sphinx-autoapi myst_parser numpydoc sphinx-astropy - name: Sphinx build run: | diff --git a/README.rst b/README.rst index ab9d33cc..4215d4d3 100644 --- a/README.rst +++ b/README.rst @@ -18,9 +18,8 @@ is simple and cross-platform, but the image is large (around 2.8GB). To install via this route, please download the `dockerfile `_ -+++++ Linux -+++++ +----- To build the docker image from the docker file, run:: @@ -33,9 +32,8 @@ And, to run the image, use:: This will mount `` in the virtual machine at `/home/hiperuser/data`. You can then run the pipeline as normal. -+++++ MacOS -+++++ +----- Installation on Apple Silicon Macs is a little more complicated. The instructions below assume you have a modern MacOS/Apple Silicon system with Docker Desktop installed. @@ -84,14 +82,14 @@ Building from Source You can build the package from source using the standard Python build tools. Prerequisites -+++++++++++++ +------------- Make sure you have the required build tools installed:: pip install build Basic Build Commands -++++++++++++++++++++ +-------------------- To build a source distribution (tarball):: @@ -206,7 +204,7 @@ your O/S package manager. e.g. under fedora, Cython appears as trm.utils : generally useful routines used at a few places. Available - from PyPi. + from PyPi. websocket-client : for talking to the hipercam server. diff --git a/docs/change_log_1.1.0_1.2.0.rst b/docs/change_log_1.1.0_1.2.0.rst index 7af21f6a..ca4d7042 100644 --- a/docs/change_log_1.1.0_1.2.0.rst +++ b/docs/change_log_1.1.0_1.2.0.rst @@ -66,7 +66,7 @@ List of changes from git, newest first, with the commit keys linked to github: * `e881e9bd98f65f9c1dcfacb3ae7fed85a104179b `_ added plotting of the max counts in plog * `db1706632c88449e541a8f077f3454149d68802c `_ cline now sets the default for the ignore value * `781022e2430bd0cda4a286b134b340afe8b04030 `_ further adjustment to docs - * `bc713d7b9f6d1e8ca3ee10e5a9a49e504a02c032 `_ utils.py strips STD_ from start of target names + * `bc713d7b9f6d1e8ca3ee10e5a9a49e504a02c032 `_ utils.py strips `STD_` from start of target names * `f6f2d350386d489cbd8c88d6cd04c589cd9bd97a `_ doc updates to describe phase II process in the main * `bb76ebc1d62cdc41b28d0dcb168acec252e95255 `_ further tweak following change to defect file * `721e56070fb4a03bf5dfb511a349828c5f6f4806 `_ new hipercam defects file following Vik's cleaning of CCD 2 diff --git a/docs/commands.rst b/docs/commands.rst index 78f46246..3028a34b 100644 --- a/docs/commands.rst +++ b/docs/commands.rst @@ -54,7 +54,7 @@ .. |ol-sub| replace:: subtract two frames .. |ol-uls| replace:: list the runs on the ULTRACAM server -.. highlightlang:: rest +.. highlight:: rest |hiper| commands **************** diff --git a/docs/conf.py b/docs/conf.py index 12f3c054..fb74188b 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -44,6 +44,8 @@ numpydoc_show_class_members = False numpydoc_show_inherited_class_members = False + +# Autoapi settings autoapi_dirs = ['../hipercam'] autoapi_generate_api_docs = False # Don't auto-generate, we'll write e.g. scripts in commands.rst @@ -55,10 +57,7 @@ templates_path = ['_templates'] # The suffix(es) of source filenames. -# You can specify multiple suffix as a list of string: -# -# source_suffix = ['.rst', '.md'] -source_suffix = '.rst' +source_suffix = {'.rst': 'restructuredtext'} # The master toctree document. master_doc = 'index' @@ -92,7 +91,7 @@ # # This is also used if you do content translation via gettext catalogs. # Usually you set "language" from the command line for these cases. -language = None +language = "en" # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. diff --git a/docs/files.rst b/docs/files.rst index 0fd47efa..a685f12b 100644 --- a/docs/files.rst +++ b/docs/files.rst @@ -2,7 +2,7 @@ .. include:: globals.rst -.. highlightlang:: rest +.. highlight:: rest Useful files ************ diff --git a/docs/index.rst b/docs/index.rst index 92bf54f6..4b52d18f 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -9,7 +9,7 @@ The |hiper| pipeline manual **************************** The |hiper| reduction software, known as the "pipeline" for short, -serves two purposes. First, it provides a means of displaying and reducing +serves two purposes. First, it provides a means of displaying and reducing |hiper|, ULTRACAM and ULTRASPEC data. Second, it provides an "Application Programmers Interface" (API) to allow you to access and manipulate the same sets of data. The first will be of @@ -19,7 +19,7 @@ aspects. It does not cover use of the |hiper| GUI or the finding chart generator, hfinder, or the equivalent components for ULTRACAM and ULTRASPEC. Details of these for |hiper| may be found on `github `_; and follows these links for much -more information on +more information on `ULTRACAM `_ and `ULTRASPEC on the TNT `_. diff --git a/docs/installation.rst b/docs/installation.rst index d295d115..eb009394 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -18,7 +18,7 @@ Updating You should keep the directory 'hipercam' created by the first ``git clone`` command because then it makes updating simple. It becomes a matter of going -to the hipercam directory, pulling the changes from github, and +to the hipercam directory, pulling the changes from github, and re-installing:: cd XXX/YYY/hipercam @@ -85,4 +85,3 @@ HIPERCAM_ENV Directory for storage of default parameter files that it does not contain too much junk. ULTRACAM_DEFAULT_URL URL of the ULTRACAM FileServer on the rack PC to access data ======================= ============================================================== - diff --git a/docs/makingmovies.rst b/docs/makingmovies.rst index ba42f26a..8903d500 100644 --- a/docs/makingmovies.rst +++ b/docs/makingmovies.rst @@ -2,7 +2,7 @@ .. include:: globals.rst -.. highlightlang:: rest +.. highlight:: rest Making |hiper| movies ********************* @@ -91,4 +91,3 @@ You can loop the movie with something like: ``ffmpeg -start_number 3 -i run0011_%04d.png -filter_complex loop=5:362 -c:v libx264 -pix_fmt yuv420p movie.mp4 -y`` which would add 6 loops. - diff --git a/docs/phaseII.rst b/docs/phaseII.rst index b0c45be4..99dd57cf 100644 --- a/docs/phaseII.rst +++ b/docs/phaseII.rst @@ -2,7 +2,7 @@ .. include:: globals.rst -.. highlightlang:: rest +.. highlight:: rest |hiper| Phase II **************** @@ -363,4 +363,3 @@ of efficiency, then windows plus "clear" might be what you want. This is because you can expose for just the exposure delay by clearing the CCD immediately before starting the exposure. With clear enabled, the exposure time just equals the exposure delay, with no added extra for the readout of the masked data. e.g. - diff --git a/docs/telescope.rst b/docs/telescope.rst index 2959a381..2c83ffe0 100644 --- a/docs/telescope.rst +++ b/docs/telescope.rst @@ -2,7 +2,7 @@ .. include:: globals.rst -.. highlightlang:: rest +.. highlight:: rest At the telescope **************** diff --git a/hipercam/hcam.py b/hipercam/hcam.py index 44b6dd5c..c977ba6a 100644 --- a/hipercam/hcam.py +++ b/hipercam/hcam.py @@ -1614,7 +1614,7 @@ def htimer(tbytes): in the FITS file Returns - -------- + ------- timestamp : (tuple) a tuple containing (frameCount, timeStampCount, years, day_of_year, diff --git a/hipercam/hlog.py b/hipercam/hlog.py index 6286fb24..3e63d08d 100644 --- a/hipercam/hlog.py +++ b/hipercam/hlog.py @@ -1191,7 +1191,7 @@ def resample( Resamples the Timeseries onto a uniform grid. Parameters - ----------- + ---------- bin_edges : `~np.ndarray` The left-hand edges of the grid. @@ -1336,7 +1336,7 @@ def bin(self, binsize, bitmask=None, inplace=True): can be used to skip points. Parameters - ----------- + ---------- binsize : int Number of observations to incude in every bin diff --git a/hipercam/scripts/aligntool.py b/hipercam/scripts/aligntool.py index 61b57c9b..16be8a59 100644 --- a/hipercam/scripts/aligntool.py +++ b/hipercam/scripts/aligntool.py @@ -221,8 +221,8 @@ def separateBigSmallSpots(xpos, ypos, fwhm, flux): Use K-Means clustering to seperate large and small starfield tube spots based on FWHM and flux. - Arguments - --------- + Parameters + ---------- xpos, ypos : np.ndarray spot locations fwhm : np.ndarray diff --git a/hipercam/window.py b/hipercam/window.py index 6f207339..a10117f0 100644 --- a/hipercam/window.py +++ b/hipercam/window.py @@ -47,8 +47,8 @@ class Winhead(Header): >>> win = Winhead(12, 6, 100, 150, 2, 3) >>> print(win) - Parameters: - ----------- + Parameters + ---------- llx : int X position of lower-left pixel of window (unbinned pixels) From d8f51ba88c7664f7062cfaf4188a30ab53dc6a5a Mon Sep 17 00:00:00 2001 From: Martin Dyer Date: Fri, 23 Jan 2026 11:52:58 +0000 Subject: [PATCH 5/6] Update documentation link --- README.rst | 3 +-- docs/conf.py | 1 - 2 files changed, 1 insertion(+), 3 deletions(-) diff --git a/README.rst b/README.rst index 4215d4d3..0f55df9d 100644 --- a/README.rst +++ b/README.rst @@ -227,8 +227,7 @@ Further Information For more information see: - * `The documentation - `_ + * `The documentation `_ * `The HiPERCAM pipeline github repository `_ diff --git a/docs/conf.py b/docs/conf.py index fb74188b..30417299 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -49,7 +49,6 @@ autoapi_dirs = ['../hipercam'] autoapi_generate_api_docs = False # Don't auto-generate, we'll write e.g. scripts in commands.rst - # number figures numfig = True From 5b774d28564fa4743b710cd419891a40f31a2cfa Mon Sep 17 00:00:00 2001 From: Martin Dyer Date: Fri, 23 Jan 2026 14:01:48 +0000 Subject: [PATCH 6/6] Fix second link --- README.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.rst b/README.rst index 0f55df9d..bf9ea27e 100644 --- a/README.rst +++ b/README.rst @@ -8,7 +8,7 @@ hipercam pipeline can also be used to reduce data from the ULTRACAM and ULTRASPEC high-speed cameras, and other instruments too. More information about using the hipercam package can be found in -`the documentation `_. +`the documentation `_. Docker Installation ===================