Merge pull request #86 from samaloney/maint-ci-packaging

Maintenance  - Docs, CI and package stuff

.editorconfig

@@ -0,0 +1,17 @@
+# https://editorconfig.org
+root=true
+# utf, UNIX-style new line
+
+[*]
+charset=utf-8
+end_of_line=lf
+insert_final_newline=true
+trim_trailing_whitespace=true
+
+[*.{py,rst,md}]
+indent_style=space
+indent_size=4
+
+[*.yml]
+indent_style=space
+indent_size=2

.github/workflows/ci.yaml

@@ -0,0 +1,53 @@
+name: CI
+
+on:
+  push:
+#    branches:
+#      - 'main'
+#      - '*.*'
+#      - '!*backport*'
+#      - '*'
+#    tags:
+#      - 'v*'
+#      - '!*dev*'
+#      - '!*pre*'
+#      - '!*post*'
+  pull_request:
+
+  # Allow manual runs through the web UI
+  workflow_dispatch:
+
+jobs:
+  core:
+    uses: OpenAstronomy/github-actions-workflows/.github/workflows/tox.yml@v1
+    with:
+      envs: |
+        - linux: codestyle
+        - linux: py39
+      coverage: 'codecov'
+    secrets:
+      CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
+
+  test:
+    needs: [core]
+    uses: OpenAstronomy/github-actions-workflows/.github/workflows/tox.yml@v1
+    with:
+      coverage: codecov
+      envs: |
+        - macos: py39
+        - windows: py39
+    secrets:
+      CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
+
+  doc:
+    needs: [test]
+    uses: OpenAstronomy/github-actions-workflows/.github/workflows/tox.yml@v1
+    with:
+      default_python: '3.9'
+      pytest: false
+      libraries: |
+        apt:
+          - libopenjp2-7
+          - graphviz
+      envs: |
+        - linux: build_docs

.pre-commit-config.yaml

@@ -1,42 +1,38 @@
 repos:
-  # The warnings/errors we check for here are:
-  # E101 - mix of tabs and spaces
-  # W191 - use of tabs
-  # W291 - trailing whitespace
-  # W292 - no newline at end of file
-  # W293 - trailing whitespace
-  # W391 - blank line at end of file
-  # E111 - 4 spaces per indentation level
-  # E112 - 4 spaces per indentation level
-  # E113 - 4 spaces per indentation level
-  # E303 - too many blank lines (3)
-  # E304 - blank lines found after function decorator
-  # E305 - expected 2 blank lines after class or function definition
-  # E306 - expected 1 blank line before a nested definition
-  # E502 - the backslash is redundant between brackets
-  # E722 - do not use bare except
-  # E901 - SyntaxError or IndentationError
-  # E902 - IOError
-  # F822: undefined name in __all__
-  # F823: local variable name referenced before assignment
-  - repo: https://github.com/pycqa/flake8
-    rev: 3.7.9
+    # This should be before any formatting hooks like isort
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: "v0.3.5"
     hooks:
-      - id: flake8
-        args: ['--count', '--select', 'E101,W191,W291,W292,W293,E111,E112,E113,E303,E304,E306,E502,E722,E901,E902,F822,F823']
-
+      - id: ruff
+        args: ["--fix"]
+  - repo: https://github.com/PyCQA/isort
+    rev: 5.13.2
+    hooks:
+      - id: isort
+        exclude: ".*(.fits|.fts|.fit|.header|.txt|tca.*|extern.*|)$"
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v2.4.0
+    rev: v4.5.0
     hooks:
       - id: check-ast
       - id: check-case-conflict
       - id: trailing-whitespace
-        exclude: ".*(.fits|.fts|.fit|.txt)$"
+        exclude: ".*(.fits|.fts|.fit|.header|.txt)$"
       - id: check-yaml
       - id: debug-statements
       - id: check-added-large-files
-        exclude: "test_data.tar.gz"
+        args: ["--enforce-all", "--maxkb=1054"]
       - id: end-of-file-fixer
-        exclude: ".*(.fits|.fts|.fit|.txt|tca.*)$"
+        exclude: ".*(.fits|.fts|.fit|.header|.txt|tca.*|.json)$|^CITATION.rst$"
       - id: mixed-line-ending
-        exclude: ".*(.fits|.fts|.fit|.txt|tca.*)$"
+        exclude: ".*(.fits|.fts|.fit|.header|.txt|tca.*)$"
+  - repo: https://github.com/codespell-project/codespell
+    rev: v2.2.6
+    hooks:
+      - id: codespell
+        additional_dependencies:
+          - tomli
+        args: ["--write-changes"]
+
+ci:
+  autofix_prs: false
+  autoupdate_schedule: "quarterly"

.readthedocs.yml

@@ -5,6 +5,9 @@
 # Required
 version: 2
 
+submodules:
+  include: all
+
 build:
   os: ubuntu-22.04
   tools:

README.rst

@@ -1,5 +1,5 @@
-Analysis software for Solar Orbiter Spectrometer Telescope for Imaging X-rays
------------------------------------------------------------------------------
+STIX Analysis Software
+----------------------
 
 .. image:: http://img.shields.io/badge/powered%20by-SunPy-orange.svg?style=flat
     :target: http://www.sunpy.org
@@ -9,10 +9,12 @@ Analysis software for Solar Orbiter Spectrometer Telescope for Imaging X-rays
     :target: https://stixpy.readthedocs.io/en/latest/?badge=latest
     :alt: Documentation Status
 
-.. image:: https://dev.azure.com/SMALONEY/stixpy/_apis/build/status/samaloney.stixpy?repoName=samaloney%2Fstixpy&branchName=master
-    :target: https://dev.azure.com/SMALONEY/stixpy/_build
+.. image:: https://github.com/samaloney/stixpy/actions/workflows/ci.yml/badge.svg
+    :target: https://github.com/samaloney/stixpy/actions/workflows/ci.yaml
     :alt: Build Status
 
+Spectrometer Telescope for Imaging X-rays (STIX) onboard Solar Orbiter (SO) python analysis software
+
 Installation
 ------------
 

docs/conf.py

@@ -1,49 +1,44 @@
-# -*- coding: utf-8 -*-
 #
 # Configuration file for the Sphinx documentation builder.
 #
 # This file does only contain a selection of the most common options. For a
 # full list see the documentation:
 # http://www.sphinx-doc.org/en/master/config
 
-import os
-import sys
-
-# sys.path.append(os.path.abspath('../'))
-
 
 # -- Project information -----------------------------------------------------
 
-project = 'STIXpy'
-copyright = '2020, STIX Team'
-author = 'STIX Team'
+project = "STIXpy"
+copyright = "2020, STIX Team"
+author = "STIX Team"
 
+from pathlib import Path
 # The full version, including alpha/beta/rc tags
-import stixpy
 from stixpy import __version__
 release = __version__
-is_development = '.dev' in release
+is_development = ".dev" in release
 
 # -- General configuration ---------------------------------------------------
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    'matplotlib.sphinxext.plot_directive',
-    'sphinx.ext.autodoc',
-    'sphinx.ext.coverage',
-    'sphinx.ext.doctest',
-    'sphinx.ext.inheritance_diagram',
-    'sphinx.ext.intersphinx',
-    'sphinx.ext.mathjax',
-    'sphinx.ext.napoleon',
-    'sphinx.ext.todo',
-    'sphinx.ext.viewcode',
-    'sphinx_automodapi.automodapi',
-    'sphinx_automodapi.smart_resolver',
-    'sphinx_changelog',
-    'sphinx_design',
+    "matplotlib.sphinxext.plot_directive",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.coverage",
+    "sphinx.ext.doctest",
+    "sphinx.ext.inheritance_diagram",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.mathjax",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.todo",
+    "sphinx.ext.viewcode",
+    "sphinx_automodapi.automodapi",
+    "sphinx_automodapi.smart_resolver",
+    "sphinx_changelog",
+    "sphinx_design",
+    "sphinx_gallery.gen_gallery",
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -52,18 +47,18 @@
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', '*.fits']
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "*.fits"]
 
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
-source_suffix = '.rst'
+source_suffix = ".rst"
 
 # The master toctree document.
-master_doc = 'index'
+master_doc = "index"
 
 # The reST default role (used for this markup: `text`) to use for all
 # documents. Set to the "smart" one.
-default_role = 'obj'
+default_role = "obj"
 
 # Disable having a separate return type row
 napoleon_use_rtype = False
@@ -75,23 +70,20 @@
 
 # Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {
-    'python': ('https://docs.python.org/3/',
-               (None, 'http://data.astropy.org/intersphinx/python3.inv')),
-    'numpy': ('https://docs.scipy.org/doc/numpy/',
-              (None, 'http://data.astropy.org/intersphinx/numpy.inv')),
-    'scipy': ('https://docs.scipy.org/doc/scipy/reference/',
-              (None, 'http://data.astropy.org/intersphinx/scipy.inv')),
-    'matplotlib': ('https://matplotlib.org/',
-                   (None, 'http://data.astropy.org/intersphinx/matplotlib.inv')),
-    'astropy': ('http://docs.astropy.org/en/stable/', None),
-    'sunpy': ('https://docs.sunpy.org/en/stable/', None)}
+    "python": ("https://docs.python.org/3/", (None, "http://data.astropy.org/intersphinx/python3.inv")),
+    "numpy": ("https://docs.scipy.org/doc/numpy/", (None, "http://data.astropy.org/intersphinx/numpy.inv")),
+    "scipy": ("https://docs.scipy.org/doc/scipy/reference/", (None, "http://data.astropy.org/intersphinx/scipy.inv")),
+    "matplotlib": ("https://matplotlib.org/", (None, "http://data.astropy.org/intersphinx/matplotlib.inv")),
+    "astropy": ("http://docs.astropy.org/en/stable/", None),
+    "sunpy": ("https://docs.sunpy.org/en/stable/", None),
+}
 
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 
-html_theme = 'pydata_sphinx_theme'
+html_theme = "pydata_sphinx_theme"
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
@@ -102,10 +94,25 @@
 graphviz_output_format = "svg"
 
 graphviz_dot_args = [
-    '-Nfontsize=10',
-    '-Nfontname=Helvetica Neue, Helvetica, Arial, sans-serif',
-    '-Efontsize=10',
-    '-Efontname=Helvetica Neue, Helvetica, Arial, sans-serif',
-    '-Gfontsize=10',
-    '-Gfontname=Helvetica Neue, Helvetica, Arial, sans-serif'
+    "-Nfontsize=10",
+    "-Nfontname=Helvetica Neue, Helvetica, Arial, sans-serif",
+    "-Efontsize=10",
+    "-Efontname=Helvetica Neue, Helvetica, Arial, sans-serif",
+    "-Gfontsize=10",
+    "-Gfontname=Helvetica Neue, Helvetica, Arial, sans-serif",
 ]
+
+# -- Options for the Sphinx gallery -------------------------------------------
+path = Path.cwd()
+example_dir = path.parent.joinpath("examples")
+sphinx_gallery_conf = {
+    "backreferences_dir": str(path.joinpath("generated", "modules")),
+    "filename_pattern": "^((?!skip_).)*$",
+    "examples_dirs": example_dir,
+    "gallery_dirs": path.joinpath("generated", "gallery"),
+    "default_thumb_file": path.joinpath("logo", "sunpy_icon_128x128.png"),
+    "abort_on_example_error": False,
+    "plot_gallery": "True",
+    "remove_config_comments": True,
+    "only_warn_on_example_error": True,
+}

docs/discussions/index.rst

@@ -0,0 +1,6 @@
+Discussions
+============
+
+.. toctree::
+
+    stix

docs/stix.rst → docs/discussions/stix.rst

@@ -1,19 +1,19 @@
 .. _stix:
 
-Instrument
-==========
+STIX
+====
 
 Introduction
 ------------
 
 STIX is an imaging X-ray spectrometer and essentially consists of 384 independent CdTe X-ray detectors which are arranged into 32 collimators each with a pixelised detector with 12 pixels.
 Thirty of these are used for normal observations, the other two serve as a background monitor and a coarse flare locator.
-Additionally STIX contains and aspect system that can determine the location of the Sun in the STIX FOV the time and spatial accuracy necessary for X-ray imaging.
+Additionally STIX contains and aspect system that can determine the location of the Sun in the STIX FOV at the time and spatial accuracy necessary for X-ray imaging.
 
 At a high level the most granular X-ray data record is pixel data (PD), that is for each pixel of
 each detector the X-ray counts for each time and energy bin are recorded. While the detectors
 count individual photons (time and energy) these are summed into 32 pre-selected energy bins (4-150)
-and rate dependant time intervals (1 - 20 s)
+and rate dependent time intervals (0.5 - 20 s)
 
 .. note::
     As SolarOrbiter is a deep space mission many of the design choices of the instrument have been

docs/dev_guide.rst → docs/how_to_guides/dev_guide.rst

@@ -11,7 +11,7 @@ The instructions in this following section are based upon resources:
 Fork and Clone Repository
 -------------------------
 Working of your own forked version of the repository is the preferred approach. To fork the
-repository visit the repository page at https://github.com/samaloney/stixpy (make sure you are logged
+repository visit the repository page at https://github.com/TCDSolar/stixpy (make sure you are logged
 into github) and click on the fork button at the to right of the page.
 
 Clone your forked version of the
@@ -24,20 +24,20 @@ It is also advisable to configure the upstream remote at this point
 
 .. code:: bash
 
-    git remote add upstream https://github.com/samaloney/stixpy
+    git remote add upstream https://github.com/TCDSolar/stixpy
 
 
 Isolated Environment
 --------------------
 It is highly recommended to work in an isolated python environment there are a number of tools
-available to help mange and create isolated environment such as
+available to help manage and create isolated environment such as
 
 * `Anaconda <https://anaconda.org>`__
 * `Pyenv <https://github.com/pyenv/pyenv>`__
 * Python 3.6+ inbuilt venv.
 
 For this documentation we will proceed using Python's venv but the step would be similar in other
-tools. For a more detailed overview see the virturl enviroment section of astropy development
+tools. For a more detailed overview see the virturl environment section of astropy development
 workflow `here <https://docs.astropy.org/en/stable/development/workflow/virtual_pythons.html#virtual-envs>`_.