diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 90ea2705..a80a683c 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -13,68 +13,87 @@ jobs: steps: - uses: actions/checkout@v4 - - name: Set up Python ${{ matrix.python-version }} + - name: Set up Python uses: actions/setup-python@v4 with: - python-version: 3.8 + python-version: "3.8" - name: pyflakes run: | pip install pyflakes pyflakes magicctapipe + docs: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - name: Set up Python + uses: actions/setup-python@v4 + with: + python-version: "3.8" + + - name: Install doc dependencies + run: | + pip install -U pip + pip install -e .[docs] + git describe --tags + python -c 'import magicctapipe; print(magicctapipe.__version__)' + + - name: Build docs + run: make doc + tests: runs-on: ubuntu-latest + strategy: matrix: - python-version: [3.8] - ctapipe-version: [v0.12.0] + python-version: ["3.8"] + ctapipe-version: ["v0.12.0"] + + defaults: + run: + # We need login shells (-l) for micromamba to work. + shell: bash -leo pipefail {0} steps: - uses: actions/checkout@v4 with: fetch-depth: 0 - - name: Set up Python ${{ matrix.python-version }} - uses: actions/setup-python@v4 + - name: Set python version ${{ matrix.python-version }} + env: + PYTHON_VERSION: ${{ matrix.python-version }} + run: | + sed -i -e "s/- python.*/- python=$PYTHON_VERSION/g" environment.yml + echo "Resulting environment file:" + cat environment.yml + + - name: mamba setup + uses: mamba-org/setup-micromamba@v1 with: - python-version: ${{ matrix.python-version }} + environment-file: environment.yml + cache-downloads: true - name: Install dependencies env: - PYTHON_VERSION: ${{ matrix.python-version }} CTAPIPE_VERSION: ${{ matrix.ctapipe-version }} - run: | - . $CONDA/etc/profile.d/conda.sh - conda config --set always_yes yes --set changeps1 no - sed -i -e "s/- python=.*/- python=$PYTHON_VERSION/g" environment.yml - conda install mamba -n base -c conda-forge - mamba env create -n ci -f environment.yml - conda activate ci - # we install ctapipe using pip to be able to select any commit, e.g. the current master - pip install pytest-cov "git+https://github.com/cta-observatory/ctapipe@$CTAPIPE_VERSION" + python --version + pip install .[all] + pip install pytest-cov pip install pyflakes - pip install -e . - git describe --tags - - #- name: Download test data - # env: - # TEST_DATA_USER: ${{ secrets.test_data_user }} - # TEST_DATA_PASSWORD: ${{ secrets.test_data_password }} - # run: | - # chmod +x ./download_test_data.sh - # ./download_test_data.sh + pip install "git+https://github.com/cta-observatory/ctapipe@$CTAPIPE_VERSION" + ctapipe-info --all + pip freeze - name: Tests env: MAGIC_CTA_DATA_USER: ${{ secrets.magic_cta_data_user }} MAGIC_CTA_DATA_PASSWORD: ${{ secrets.magic_cta_data_password }} run: | - # github actions starts a new shell for each "step", so we need to - # activate our env again - source $CONDA/etc/profile.d/conda.sh - conda activate ci coverage run -m pytest -v coverage xml diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 9138a7fe..b2f7c443 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -3,11 +3,14 @@ version: "2" build: os: "ubuntu-22.04" tools: - python: "3.10" + python: "3.8" python: install: - - requirements: docs/requirements.txt + - method: pip + path: . + extra_requirements: + - docs sphinx: - configuration: docs/source/conf.py + configuration: docs/conf.py diff --git a/Makefile b/Makefile new file mode 100644 index 00000000..7e35a0be --- /dev/null +++ b/Makefile @@ -0,0 +1,63 @@ +# Makefile with some convenient quick ways to do common things + +PROJECT=magic-cta-pipe +PYTHON=python + +help: + @echo '' + @echo '$(PROJECT) available make targets:' + @echo '' + @echo ' help Print this help message (the default)' + @echo ' env Create a conda environment for magic-cta-pipe development' + @echo ' develop make symlinks to this package in python install dir' + @echo ' clean Remove temp files' + @echo ' test Run tests' + @echo ' doc Generate Sphinx docs' + @echo ' analyze Do a static code check and report errors' + @echo '' + @echo 'Advanced targets (for experts)' + @echo ' conda Build a conda package for distribution' + @echo ' doc-publish Upload docs to static GitHub page' + @echo '' + +init: + @echo "'make init' is no longer needed" + +clean: + $(RM) -rf build docs/_build docs/api htmlcov magic_cta_pipe.egg-info dist + find . -name "*.pyc" -exec rm {} \; + find . -name "*.so" -exec rm {} \; + find . -name __pycache__ | xargs rm -fr + +test: + pytest + +doc: + cd docs && $(MAKE) html SPHINXOPTS="-W --keep-going -n --color -j auto" + @echo "------------------------------------------------" + @echo "Documentation is in: docs/_build/html/index.html" + +doc-publish: + ghp-import -n -p -m 'Update gh-pages docs' docs/_build/html + +analyze: + @pylint magicctapipe --ignored-classes=astropy.units + +lint: + @flake8 magicctapipe + +env: + conda env create -n cta-dev -f environment.yml + source activate cta-dev + +develop: + pip install -e . + +wheel: + python -m build --wheel + +sdist: + python -m build --sdist + +trailing-spaces: + find $(PROJECT) examples docs -name "*.py" -exec perl -pi -e 's/[ \t]*$$//' {} \; diff --git a/docs/Makefile b/docs/Makefile index d0c3cbf1..84999a8f 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -3,18 +3,24 @@ # You can set these variables from the command line, and also # from the environment for the first two. -SPHINXOPTS ?= -SPHINXBUILD ?= sphinx-build -SOURCEDIR = source -BUILDDIR = build +SPHINXOPTS = -W --keep-going -n --color +SPHINXBUILD = sphinx-build +SPHINXPROJ = magic-cta-pipe +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) + +clean: + rm -rf api auto_examples + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + + +.PHONY: all help clean Makefile diff --git a/docs/_static/switcher.json b/docs/_static/switcher.json new file mode 100644 index 00000000..0b81c553 --- /dev/null +++ b/docs/_static/switcher.json @@ -0,0 +1,17 @@ +[ + { + "name": "dev", + "version": "latest", + "url": "https://magic-cta-pipe.readthedocs.io/en/latest/" + }, + { + "name": "stable", + "version": "stable", + "url": "https://magic-cta-pipe.readthedocs.io/en/stable/" + }, + { + "name": "v0.3.1", + "version": "v0.3.1", + "url": "https://magic-cta-pipe.readthedocs.io/en/v0.3.1/" + } +] \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 00000000..44f4ac00 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,131 @@ +# Configuration file for the Sphinx documentation builder. + +import datetime +import os + +import magicctapipe + +# Get configuration information from setup.cfg +from configparser import ConfigParser + +setup_cfg = ConfigParser() +setup_cfg.read([os.path.join(os.path.dirname(__file__), "..", "setup.cfg")]) +setup_metadata = dict(setup_cfg.items("metadata")) +setup_options = dict(setup_cfg.items("options")) + +# -- Project information + +project = setup_metadata["name"] +author = setup_metadata["author"] +copyright = "{}. Last updated {}".format( + setup_metadata["author"], datetime.datetime.now().strftime("%d %b %Y %H:%M") +) +python_requires = setup_options["python_requires"] + +# make some variables available to each page +rst_epilog = f""" +.. |python_requires| replace:: {python_requires} +""" + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. + +version = magicctapipe.__version__ +# The full version, including alpha/beta/rc tags. +release = version + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = "en" + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = "sphinx" + +# Define the json_url for our version switcher. +json_url = "https://magic-cta-pipe.readthedocs.io/en/latest/_static/switcher.json" + +# Define the version we use for matching in the version switcher., +version_match = os.getenv("READTHEDOCS_VERSION") +# If READTHEDOCS_VERSION doesn't exist, we're not on RTD +# If it is an integer, we're in a PR build and the version isn't correct. +if not version_match or version_match.isdigit(): + # For local development, infer the version to match from the package. + if "dev" in release or "rc" in release: + version_match = "latest" + else: + version_match = release + + # We want to keep the relative reference when on a pull request or locally + json_url = "_static/switcher.json" + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +html_theme_options = { + "github_url": "https://github.com/cta-observatory/magic-cta-pipe", + "header_links_before_dropdown": 6, + "navbar_start": ["navbar-logo", "version-switcher"], + "switcher": { + "version_match": version_match, + "json_url": json_url, + }, + "use_edit_page_button": True, + "icon_links_label": "Quick Links", + "icon_links": [ + { + "name": "CTA Observatory", + "url": "https://www.cta-observatory.org/", + "type": "url", + "icon": "https://www.cta-observatory.org/wp-content/themes/ctao/favicon.ico", + }, + ], + "announcement": """ +

magic-cta-pipe is under active development. Expect large and rapid changes in functionality.

+ """, +} + +# 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, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ["_static"] +html_context = { + "default_mode": "light", + "github_user": "cta-observatory", + "github_repo": "magic-cta-pipe", + "github_version": "master", + "doc_path": "docs", +} + + +# -- General configuration + +extensions = [ + 'sphinx.ext.duration', + 'sphinx.ext.doctest', + 'sphinx.ext.autodoc', + 'sphinx.ext.autosummary', + 'sphinx.ext.intersphinx', +] + +intersphinx_mapping = { + 'python': ('https://docs.python.org/3/', None), + 'sphinx': ('https://www.sphinx-doc.org/en/master/', None), +} +intersphinx_disabled_domains = ['std'] + +templates_path = ['_templates'] + +# -- Options for HTML output + +html_theme = 'pydata_sphinx_theme' + +# The name for this set of Sphinx documents. If None, it defaults to +# " v documentation". +html_title = f"{project} v{release}" + +# -- Options for EPUB output +epub_show_urls = 'footnote' diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 00000000..c1ef88e3 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,31 @@ +.. _magicctapipe: + +============================================ +Welcome to ``magic-cta-pipe`` documentation! +============================================ + +.. currentmodule:: magicctapipe + +**Version**: |version| **Date**: |today| + +**Useful links**: +`Source Repository `__ | +`Issue Tracker `__ | +`Discussions `__ + +**License**: BSD-3 + +**magic-cta-pipe** is a pipeline for the analysis of joint data taken with MAGIC and LST-1. + +Check out the :doc:`usage` section for the analysis steps, including how to :ref:`installation` the project. + +.. note:: + + This project is under active development. + +Contents +-------- + +.. toctree:: + + usage \ No newline at end of file diff --git a/docs/source/conf.py b/docs/source/conf.py deleted file mode 100644 index 35b137b0..00000000 --- a/docs/source/conf.py +++ /dev/null @@ -1,35 +0,0 @@ -# Configuration file for the Sphinx documentation builder. - -# -- Project information - -project = 'magic-cta-pipe' -copyright = '2023, the magic-cta-pipe developers' -author = 'magic-cta-pipe developers' - -release = '0.3.1' -version = '0.3.1' - -# -- General configuration - -extensions = [ - 'sphinx.ext.duration', - 'sphinx.ext.doctest', - 'sphinx.ext.autodoc', - 'sphinx.ext.autosummary', - 'sphinx.ext.intersphinx', -] - -intersphinx_mapping = { - 'python': ('https://docs.python.org/3/', None), - 'sphinx': ('https://www.sphinx-doc.org/en/master/', None), -} -intersphinx_disabled_domains = ['std'] - -templates_path = ['_templates'] - -# -- Options for HTML output - -html_theme = 'sphinx_rtd_theme' - -# -- Options for EPUB output -epub_show_urls = 'footnote' \ No newline at end of file diff --git a/docs/source/index.rst b/docs/source/index.rst deleted file mode 100644 index 437adf7f..00000000 --- a/docs/source/index.rst +++ /dev/null @@ -1,17 +0,0 @@ -Welcome to magic-cta-pipe documentation! -=================================== - -**magic-cta-pipe** is a pipeline for the analysis of joint data taken with MAGIC and LST-1. - -Check out the :doc:`usage` section for the analysis steps, including how to :ref:`installation` the project. - -.. note:: - - This project is under active development. - -Contents --------- - -.. toctree:: - - usage \ No newline at end of file diff --git a/docs/source/usage.rst b/docs/usage.rst similarity index 100% rename from docs/source/usage.rst rename to docs/usage.rst diff --git a/environment.yml b/environment.yml index fd30be37..296e8e17 100644 --- a/environment.yml +++ b/environment.yml @@ -1,7 +1,6 @@ # A conda environment with all useful package for ctapipe developers name: magic-lst1 channels: - - default - conda-forge dependencies: - python=3.8 @@ -29,6 +28,7 @@ dependencies: - sphinx - sphinx-automodapi - sphinx_rtd_theme + - pydata-sphinx-theme - uproot~=4.1 - corsikaio - pip: diff --git a/setup.py b/setup.py index f8c4a145..58ec1149 100644 --- a/setup.py +++ b/setup.py @@ -25,6 +25,7 @@ "sphinx-automodapi", "sphinx_argparse", "sphinx_rtd_theme", + "pydata_sphinx_theme", "numpydoc", "nbsphinx", ] @@ -39,6 +40,7 @@ 'ctaplot~=0.5.5', 'gammapy~=0.19.0', 'uproot~=4.1', + 'numba<=0.56', 'numpy<1.22.0a0', 'joblib', 'pandas',