Merge pull request #3 from ericpre/doc_build

Add doc workflow

.github/workflows/build.yml

@@ -21,9 +21,9 @@ jobs:
           python --version
           pip --version
 
-      - name: Install pypa/build
+      - name: Install pypa/build pypa/twine
         run: |
-          pip install build
+          pip install build twine
 
       - name: Build a binary wheel and a source tarball
         run: |
@@ -32,6 +32,10 @@ jobs:
       - name: Display content dist folder
         run: |
           ls -l dist/
+      
+      - name: Run twin check
+        run: |
+          twine check dist/*
 
       - uses: actions/upload-artifact@v3
         with:

.github/workflows/docs.yml

@@ -0,0 +1,97 @@
+name: Docs
+
+on: [push, pull_request]
+
+jobs:
+  build_docs:
+    # This build is to make PR comments for the sphinx warning and check if
+    # web links are not broken 
+    name: Check links and make PR comments
+    runs-on: ubuntu-latest
+    env:
+      DOCS_PATH: ./doc/_build/html/
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v4
+        name: Install Python
+        with:
+          python-version: '3.11'
+
+      - name: Install build docs
+        shell: bash -l {0}
+        run: |
+          pip install .'[doc]'
+      
+      # Add sphinx warnings as PR comments
+      - uses: sphinx-doc/sphinx-problem-matcher@master
+
+      - name: Build docs
+        shell: bash -l {0}
+        run: |
+          cd doc
+          make SPHINXOPTS="-W --keep-going" html
+
+      - uses: actions/upload-artifact@v3
+        with:
+          path: ${{ env.DOCS_PATH }}
+          name: docs_html
+
+      - name: Check links
+        shell: bash -l {0}
+        run: |
+          cd doc
+          make linkcheck
+
+  push_docs:
+    # This build is to push changes to gh-pages branch (https://hyperspy.org/exspy)
+    needs: build_docs
+    name: Push to gh-pages
+    runs-on: ubuntu-latest
+    if: ${{ github.event_name != 'pull_request' && github.repository == 'hyperspy/exspy' }}
+    permissions:
+      # needs write permission to push the docs to gh-pages
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          ref: gh-pages
+
+      - uses: actions/download-artifact@v3
+        with:
+          name: docs_html
+          path: .
+
+      - name: list files
+        run: |
+          ls
+
+      - name: Git status
+        run: |
+          git status
+          git status -s
+          if [[ $(git status -s) ]]; then
+            HAS_CHANGES='true'
+          else
+            HAS_CHANGES='false'
+          fi
+          echo "HAS_CHANGES=${HAS_CHANGES}" >> $GITHUB_ENV
+
+      - name: Commit files
+        # Skip when there is nothing to commit
+        if: ${{ env.HAS_CHANGES == 'true' }}
+        run: |
+          git config --local user.email "github-actions[bot]@users.noreply.github.com"
+          git config --local user.name "github-actions[bot]"
+          git add -A
+          git commit -m "Update docs build" -a
+
+      - name: Push changes
+        if: ${{ env.HAS_CHANGES == 'true' }}
+        uses: ad-m/github-push-action@d91a481090679876dfc4178fef17f286781251df
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          branch: gh-pages

.github/workflows/tests.yml

@@ -45,7 +45,7 @@ jobs:
 
       - name: Run test suite
         run: |
-          pytest --pyargs exspy
+          pytest --pyargs exspy -n 2
 
       - name: Upload coverage to Codecov
         if: ${{ always() }}

.gitignore

@@ -0,0 +1,5 @@
+doc/_build/*
+doc/auto_examples/*
+build/*
+dist/*
+*egg-info*

.readthedocs.yaml

@@ -0,0 +1,27 @@
+# .readthedocs.yml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the version of Python and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+  configuration: doc/conf.py
+
+# Optionally build your docs in additional formats such as PDF and ePub
+formats:
+  - htmlzip
+
+python:
+   install:
+      - method: pip
+        path: .
+        extra_requirements:
+           - doc

README.md

@@ -0,0 +1,14 @@
+
+**exSpy** is a Python package extending the functionality for multi-dimensional
+data analysis provided by the [HyperSpy](https://hyperspy.org) library. It is
+aimed at helping with the analysis of X-rays Energy Dispersive Spectroscopy (EDS)
+and Electron Energy Loss Spectroscopy (EELS).
+
+Go to the documentation for instructions on how to install exSpy and start an
+analysis: [Read the docs](https://exspy.readthedocs.io).
+
+Everyone is welcome to contribute. Please read our
+[contributing guidelines](https://github.com/hyperspy/exspy/blob/main/CONTRIBUTING.rst) and get started!
+
+Development of exSpy is documented in the
+[changelog](https://github.com/hyperspy/exspy/blob/main/CHANGES.rst).

doc/citing.rst

@@ -6,7 +6,7 @@ Citing exSpy
 
 If exSpy has been significant to a project that leads to an academic
 publication, please acknowledge that fact by citing it. The DOI in the
-badge below is the `Concept DOI <https://help.zenodo.org/fag/#versioning>`_ --
+badge below is the `Concept DOI <https://help.zenodo.org/faq/#versioning>`_ --
 it can be used to cite the project without referring to a specific
 version. If you are citing HoloSpy because you have used it to process data,
 please use the DOI of the specific version that you have employed. You can

doc/conf.py

@@ -35,11 +35,24 @@
     # "numpydoc",
     "sphinx_design",
     "sphinx_favicon",
+    "sphinx_copybutton",
     "sphinx.ext.autodoc",
     "sphinx.ext.autosummary",
     "sphinx.ext.githubpages",
     "sphinx.ext.intersphinx",
     "sphinx.ext.napoleon",
+    "sphinx_gallery.gen_gallery",
+]
+
+linkcheck_ignore = [
+    "https://doi.org/10.1021/acs.nanolett.5b00449",  # 403 Client Error: Forbidden for url
+    "https://onlinelibrary.wiley.com/doi/10.1111/j.1365-2818.2006.01549.x",  # 403 Client Error: Forbidden for url
+    # Remove when setup
+    "https://github.com/hyperspy/exspy-demos",
+    "https://www.anaconda.com/blog/understanding-conda-and-pip",  # Transcient?
+    # Remove once it is merged and the links are working
+    "https://exspy.readthedocs.io",
+    "https://github.com/hyperspy/exspy/blob/main/releasing_guide.md",
 ]
 
 intersphinx_mapping = {
@@ -87,6 +100,7 @@
         "text": "exSpy",
     },
     "header_links_before_dropdown": 6,
+    "navigation_with_keys": False,
 }
 
 # The name of an image file (relative to this directory) to place at the top
@@ -119,5 +133,17 @@
 }
 toc_object_entries_show_parents = "hide"
 
-# def setup(app):
-#     app.add_css_file("custom-styles.css")
+# -- Sphinx-Gallery---------------
+
+# https://sphinx-gallery.github.io
+sphinx_gallery_conf = {
+    "examples_dirs": "../examples",  # path to your example scripts
+    "gallery_dirs": "auto_examples",  # path to where to save gallery generated output
+    "filename_pattern": ".py",  # pattern to define which will be executed
+    "ignore_pattern": "_sgskip.py",  # pattern to define which will not be executed
+}
+
+# -- Sphinx-copybutton -----------
+
+copybutton_prompt_text = r">>> |\.\.\. "
+copybutton_prompt_is_regexp = True

doc/index.rst

@@ -1,29 +1,12 @@
-Welcome to exSpy's documentation!
-***********************************
-**exSpy** is a Python package extending the functionality for multi-dimensional
-data analysis provided by the `HyperSpy <https://hyperspy.org/>`_ library. It is
-aimed at helping with the analysis of X-rays Energy Dispersive Spectroscopy (EDS)
-and Electron Energy Loss Spectroscopy (EELS).
-
-Check out the :ref:`installation <install-label>` section for further information, including
-how to start using this project.
-
-.. note::
-
-   This is an open-source community project: everyone is welcome to contribute.
-   Please read our (see :ref:`contributing_label`) guidelines and get started!
-
-Contents
-========
-
 .. toctree::
-   :maxdepth: 2
-
-   user_guide/index.rst
-   reference/index.rst
-   changes.rst
-   Citing <citing.rst>
-   contributing.rst
-   license.rst
+   :maxdepth: 1
+   :hidden:
+
+   User Guide <user_guide/index>
+   Examples <auto_examples/index>
+   Reference <reference/index>
+   Release Notes <changes>
+   Citing <citing>
+   Contribute <contributing>
 
 .. include:: intro.rst

doc/intro.rst

@@ -1,12 +1,18 @@
+Welcome to exSpy's documentation!
+***********************************
+**exSpy** is a Python package extending the functionality for multi-dimensional
+data analysis provided by the `HyperSpy <https://hyperspy.org/>`_ library. It is
+aimed at helping with the analysis of X-rays Energy Dispersive Spectroscopy (EDS)
+and Electron Energy Loss Spectroscopy (EELS).
 
-What is exSpy
-=============
+Check out the :ref:`installation <install-label>` section for further information,
+including how to start using this project.
 
-exSpy is an open source Python library which provides tools to facilitate
-the visualization and processing of EELS EDS and other spectroscopic data.
+.. note::
+
+   This is an open-source community project: everyone is welcome to contribute.
+   Please read our (see :ref:`contributing_label`) guidelines and get started!
 
-exSpy is built on top of HyperSpy, a Python library for multi-dimensional
-data analysis and extends it with tools for the analysis of spectroscopic data.
 
 Learning resources
 ==================
@@ -73,11 +79,11 @@ Learning resources
     There are many ways you can help!
 
 Citing exSpy
-=================
+============
 
 If exSpy has been significant to a project that leads to an academic
 publication, please acknowledge that fact by citing it. The DOI in the
-badge below is the `Concept DOI <https://help.zenodo.org/#versioning>`_ of
+badge below is the `Concept DOI <https://help.zenodo.org/faq/#versioning>`_ of
 HyperSpy. It can be used to cite the project without referring to a specific
 version. If you are citing exSpy because you have used it to process data,
 please use the DOI of the specific version that you have employed. You can
@@ -98,7 +104,18 @@ HyperSpy in a scientific database e.g. `Google Scholar
     Articles published before 2012 may mention the HyperSpy project under
     its old name, `EELSLab`.
 
-Credits
+
+License
 =======
 
-.. include:: ../AUTHORS.txt
+**exSpy** is free software: you can redistribute it and/or modify
+it under the terms of the `GNU General Public License (GPL)
+<https://www.gnu.org/licenses/#GPL>`_ as published by
+the Free Software Foundation, either version 3 of the license, or
+(at your option) any later version.
+
+**exSpy** is distributed in the hope that it will be useful,
+but **without any warranty**; without even the implied warranty of
+**merchantability** or **fitness for a particular purpose**. See the
+`GNU General Public License <https://www.gnu.org/licenses/#GPL>`_
+for more details.

doc/user_guide/index.rst

@@ -5,7 +5,6 @@ User Guide
 ##########
 
 .. toctree::
-   :caption: User Guide
    :maxdepth: 2
 
    install