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