Merge pull request #290 from alhom/master

Add Sphinx autodoc and GitHub pages

.github/workflows/sphinx.yml

@@ -0,0 +1,172 @@
+# Deploy Sphinx.  This could be shorter, but we also do some extra
+# stuff.
+#
+# License: CC-0.  This is the canonical location of this file, which
+# you may want to link to anyway:
+#   https://github.com/coderefinery/sphinx-lesson-template/blob/main/.github/workflows/sphinx.yml
+#  https://raw.githubusercontent.com/coderefinery/sphinx-lesson-template/main/.github/workflows/sphinx.yml
+
+
+name: sphinx
+on: [push, pull_request]
+
+env:
+  DEFAULT_BRANCH: "master"
+  # If these SPHINXOPTS are enabled, then be strict about the
+  # builds and fail on any warnings.
+  #SPHINXOPTS: "-W --keep-going -T"
+  GENERATE_PDF: false          # to enable, must be 'true' lowercase
+  GENERATE_SINGLEHTML: false   # to enable, must be 'true' lowercase
+  PDF_FILENAME: lesson.pdf
+  MULTIBRANCH: false    # to enable, must be 'true' lowercase
+
+
+jobs:
+  build:
+    name: Build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+
+    steps:
+      # https://github.com/marketplace/actions/checkout
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          lfs: true
+
+      # https://github.com/marketplace/actions/setup-python
+      # ^-- This gives info on matrix testing.
+      - name: Install Python
+        uses: actions/setup-python@v3
+        # with:
+        #   python-version: '3.11'
+        #   cache: 'pip'
+
+      # https://docs.github.com/en/actions/guides/building-and-testing-python#installing-dependencies
+      # ^-- This gives info on installing dependencies with pip
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
+          python -m pip install sphinx numpy scipy matplotlib scikit-image numba yt geopack sphinx-rtd-theme
+
+        # Debug
+      - name: Debugging information
+        env:
+          ref: ${{github.ref}}
+          event_name: ${{github.event_name}}
+          head_ref: ${{github.head_ref}}
+          base_ref: ${{github.base_ref}}
+        run: |
+          echo "github.ref: ${ref}"
+          echo "github.event_name: ${event_name}"
+          echo "github.head_ref: ${head_ref}"
+          echo "github.base_ref: ${base_ref}"
+          echo "GENERATE_PDF: ${GENERATE_PDF}"
+          echo "GENERATE_SINGLEHTML: ${GENERATE_SINGLEHTML}"
+          set -x
+          git rev-parse --abbrev-ref HEAD
+          git branch
+          git branch -a
+          git remote -v
+          python -V
+          pip list --not-required
+          pip list
+
+
+      # Build
+      - uses: ammaraskar/sphinx-problem-matcher@master
+      - name: Build Sphinx docs (dirhtml)
+        # SPHINXOPTS used via environment variables
+        run: |
+          cd Documentation/sphinx/
+          make dirhtml
+          # This fixes broken copy button icons, as explained in
+          #   https://github.com/coderefinery/sphinx-lesson/issues/50
+          #   https://github.com/executablebooks/sphinx-copybutton/issues/110
+          # This can be removed once these PRs are accepted (but the
+          # fixes also need to propagate to other themes):
+          #   https://github.com/sphinx-doc/sphinx/pull/8524
+          #   https://github.com/readthedocs/sphinx_rtd_theme/pull/1025
+          sed -i 's/url_root="#"/url_root=""/' _build/dirhtml/index.html || true
+
+      # singlehtml
+      - name: Generate singlehtml
+        if: ${{ env.GENERATE_SINGLEHTML == 'true' }}
+        run: |
+          make singlehtml
+          mv _build/singlehtml/ _build/dirhtml/singlehtml/
+
+      # PDF if requested
+      - name: Generate PDF
+        if: ${{ env.GENERATE_PDF == 'true' }}
+        run: |
+          pip install https://github.com/rkdarst/sphinx_pyppeteer_builder/archive/refs/heads/main.zip
+          make pyppeteer
+          mv _build/pyppeteer/*.pdf _build/dirhtml/${PDF_FILENAME}
+
+      # Stage all deployed assets in _gh-pages/ for simplicity, and to
+      # prepare to do a multi-branch deployment.
+      - name: Copy deployment data to _gh-pages/
+        if: ${{ github.event_name == 'push' }}
+        run:
+          rsync -a Documentation/sphinx/_build/dirhtml/ _gh-pages/
+
+      # Use gh-pages-multibranch to multiplex different branches into
+      # one deployment. See
+      # https://github.com/coderefinery/gh-pages-multibranch
+      - name: gh-pages multibranch
+        uses: coderefinery/gh-pages-multibranch@main
+        if: ${{ github.event_name == 'push' && env.MULTIBRANCH == 'true' }}
+        with:
+          directory: _gh-pages/
+          default_branch: ${{ env.DEFAULT_BRANCH }}
+          publish_branch: gh-pages
+
+      # Add the .nojekyll file
+      - name: nojekyll
+        if: ${{ github.event_name == 'push' }}
+        run: |
+          touch _gh-pages/.nojekyll
+
+      # Save artifact for the next step.
+      - uses: actions/upload-artifact@v4
+        if: ${{ github.event_name == 'push' }}
+        with:
+          name: gh-pages-build
+          path: _gh-pages/
+
+  # Deploy in a separate job so that write permissions are restricted
+  # to the minimum steps.
+  deploy:
+    name: Deploy
+    runs-on: ubuntu-latest
+    needs: build
+    # This if can't use the env context - find better way later.
+    if: ${{ github.event_name == 'push' }}
+    permissions:
+      contents: write
+
+    steps:
+      - uses: actions/download-artifact@v4
+        if: ${{ github.event_name == 'push' && ( env.MULTIBRANCH == 'true' || github.ref == format('refs/heads/{0}', env.DEFAULT_BRANCH )) }}
+        with:
+          name: gh-pages-build
+          path: _gh-pages/
+
+      # As of 2023, we could publish to pages via a Deployment.  This
+      # isn't done yet to give it time to stabilize (out of beta), and
+      # also having a gh-pages branch to check out is rather
+      # convenient.
+
+      # Deploy
+      # https://github.com/peaceiris/actions-gh-pages
+      - name: Deploy
+        uses: peaceiris/actions-gh-pages@v3
+        if: ${{ github.event_name == 'push' && ( env.MULTIBRANCH == 'true' || github.ref == format('refs/heads/{0}', env.DEFAULT_BRANCH )) }}
+        with:
+          publish_branch: gh-pages
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: _gh-pages/
+          force_orphan: true

Documentation/sphinx/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)

Documentation/sphinx/about.rst

@@ -0,0 +1,8 @@
+.. about credits, etc
+
+
+Credits
+=======
+
+The pilot version of this automatic documentation was constructed by Sameli Siljamo during his two-week work-life trainee period.
+

Documentation/sphinx/biot_savart.rst

@@ -0,0 +1,5 @@
+biot_savart
+-----------
+
+.. automodule:: biot_savart
+	:members:

Documentation/sphinx/calculations.rst

@@ -0,0 +1,6 @@
+calculations
+=================================
+
+.. automodule:: pytools.calculations
+   :members:
+   :imported-members:

Documentation/sphinx/conf.py

@@ -0,0 +1,37 @@
+# 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
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path('..', '..').resolve()))
+sys.path.insert(0, str(Path('..', '..', 'scripts').resolve()))
+print(str(Path('..','..').resolve()))
+print(str(Path('..','..', 'scripts').resolve()))
+project = 'analysator'
+copyright = '2024, University of Helsinki'
+author = 'Sameli'
+
+# -- 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 = 'sphinx_rtd_theme'
+html_logo = "logo_color.png"
+html_static_path = ['_static']

Documentation/sphinx/fetchscripts.py

@@ -0,0 +1,19 @@
+import glob
+import os
+
+files = glob.glob('C:/Users/samel/OneDrive/Tiedostot/TET/analysator/scripts/*.py')
+
+for file in files:
+    file = os.path.basename(file)[:-3]
+    print(file)
+    with open('scripts.rst', 'a') as f:
+        f.write(file + "\n")
+        f.write("-"*len(file)+ "\n")
+        f.write("\n" + ".. automodule:: " + (file) + "\n")
+        f.write("\n" + "------------\n\n")
+
+    # with open(file + '.rst', 'w') as f:
+    #    f.write(file + "\n")
+    #    f.write("-"*len(file)+ "\n")
+    #    f.write("\n" + ".. automodule:: " + (file) + "\n")
+    #    f.write("\t:members:")

Documentation/sphinx/gics.rst

@@ -0,0 +1,5 @@
+gics
+----
+
+.. automodule:: gics
+	:members:

Documentation/sphinx/index.rst

@@ -0,0 +1,40 @@
+.. analysator documentation master file, created by
+   sphinx-quickstart on Tue Oct 29 10:43:26 2024.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+analysator documentation
+========================
+
+.. .. image:: logo_color.png
+..    :height: 37
+..    :width: 300
+..    :scale: 75
+..    :align: right
+..    :alt: Vlasiator Logo
+
+`Analysator <https://github.com/fmihpc/analysator>`_ is a set of Python tools and scripts used to read and analyze `Vlasiator <https://github.com/fmihpc/vlasiator>`_ output files (`VLSV <https://github.com/fmihpc/vlsv>`_). Vlasiator and its related tools are developed at `University of Helsinki <https://www.helsinki.fi/en/researchgroups/vlasiator>`_, and are open source. 
+
+
+This documentation is generated via Sphinx-autodoc from Analysator source. This page is a work in progress, with docstrings and the documentation layout in flux. Contributions via Analysator repo are welcome.
+
+Add your content using ``reStructuredText`` syntax. See the
+`reStructuredText <https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html>`_
+documentation for details.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   plot
+   calculations
+   vlsvfile
+   miscellaneous
+   scripts
+   about
+
+.. automodule:: pytools 
+   :members:
+   :imported-members:
+   :undoc-members:
+

Documentation/sphinx/magnetopause2d.rst

@@ -0,0 +1,5 @@
+magnetopause2d
+--------------
+
+.. automodule:: magnetopause2d
+	:members:

Documentation/sphinx/magnetopause3d.rst

@@ -0,0 +1,5 @@
+magnetopause3d
+--------------
+
+.. automodule:: magnetopause3d
+	:members:

Documentation/sphinx/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

Documentation/sphinx/miscellaneous.rst

@@ -0,0 +1,6 @@
+miscellaneous
+==================================
+
+.. automodule:: pytools.miscellaneous
+   :members:
+   :imported-members:

Documentation/sphinx/plot.rst

@@ -0,0 +1,8 @@
+plot
+============================
+
+.. automodule:: pytools.plot
+   :members:
+   :exclude-members: Version
+   :imported-members:
+