Merge pull request #159 from cta-observatory/automatic_docs

Add deployment of docs in CI

.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
 

.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

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]*$$//' {} \;

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

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/"
+    }
+]

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": """
+        <p>magic-cta-pipe is under active development. Expect large and rapid changes in functionality.</p>
+    """,
+}
+
+# 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
+# "<project> v<release> documentation".
+html_title = f"{project} v{release}"
+
+# -- Options for EPUB output
+epub_show_urls = 'footnote'