NSLS-II

.github/workflows/docs.yml

@@ -0,0 +1,76 @@
+name: Docs
+
+on:
+  push:
+  pull_request:
+
+
+jobs:
+  publish-docs:
+    name: Build and publish documentation
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.8", "3.9", "3.10"]
+      fail-fast: false
+
+    defaults:
+      run:
+        shell: bash -l {0}
+
+    steps:
+      - name: Set environment variable
+        run: |
+          export REPOSITORY_NAME=${GITHUB_REPOSITORY#*/}  # just the repo, as opposed to org/repo
+          echo "REPOSITORY_NAME=${REPOSITORY_NAME}" >> $GITHUB_ENV
+
+      - uses: actions/checkout@v3
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Build example code
+        shell: 'script --return --quiet --command "bash -l {0}"'
+        run: |
+            set -vxeo pipefail
+
+            pip install -r requirements.txt
+            ./run_cookiecutter_example.py
+
+            # Test the style with pre-commit
+            cd example/
+            git config --global user.name "CI Tester"
+            git config --global user.email "[email protected]"
+            git init
+            git add .
+            git commit -m "Initial commit"
+            pre-commit run --all-files
+            cd ..
+
+            pip install -e example/
+            ./copy_user_content.sh
+            pytest example/
+            
+      - name: Build docs
+        run: make -C docs html
+
+      - uses: actions/upload-artifact@v3
+        with:
+          name: ${{ env.REPOSITORY_NAME }}-py${{ matrix.python-version }}-docs
+          path: docs/build/html/
+
+      - name: Publish docs
+        # We pin to the SHA, not the tag, for security reasons.
+        # https://docs.github.com/en/free-pro-team@latest/actions/learn-github-actions/security-hardening-for-github-actions#using-third-party-actions
+        if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' && matrix.python-version == '3.9' }}
+        uses: peaceiris/actions-gh-pages@bbdfb200618d235585ad98e965f4aafc39b4c501  # v3.7.3
+        with:
+          deploy_key: ${{ secrets.ACTIONS_DOCUMENTATION_DEPLOY_KEY }}
+          publish_branch: master
+          publish_dir: ./docs/build/html
+          external_repository: NSLS-II/NSLS-II.github.io
+          destination_dir: ${{ env.REPOSITORY_NAME }}
+          keep_files: true  # Keep old files.
+          force_orphan: false  # Keep git history.

cookiecutter.json

@@ -0,0 +1,16 @@
+{
+    "full_name": "Name or Organization",
+    "email": "",
+    "github_username": "",
+    "project_name": "Your Project Name",
+    "package_dist_name": "{{ cookiecutter.project_name|replace(' ', '-')|lower }}",
+    "package_dir_name": "{{ cookiecutter.project_name|replace(' ', '_')|replace('-', '_')|lower }}",
+    "repo_name": "{{ cookiecutter.project_name|replace(' ', '-')|lower }}",
+    "project_short_description": "Python package for doing science.",
+    "minimum_supported_python_version": ["3.8", "3.9", "3.10"],
+    "_copy_without_render": [
+        "*.html",
+        "*.js",
+        ".github/*"
+    ]
+}

copy_user_content.sh

@@ -0,0 +1,3 @@
+#!/bin/bash
+cp docs/source/refraction.py example/example/refraction.py
+cp docs/source/test_examples.py example/example/tests/test_examples.py

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    = "-W"  # This flag turns warnings into errors.
+SPHINXBUILD   = sphinx-build
+SPHINXPROJ    = PackagingScientificPython
+SOURCEDIR     = source
+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)

docs/make.bat

@@ -0,0 +1,36 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+set SPHINXPROJ=PackagingScientificPython
+
+if "%1" == "" goto help
+
+%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.http://sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
+
+:end
+popd

docs/source/advanced-testing.rst

@@ -0,0 +1,155 @@
+=========================
+Common Patterns for Tests
+=========================
+
+In this section you will learn some useful features of pytest that can make
+your tests succinct and easy to maintain.
+
+Parametrized Tests
+------------------
+
+Tests that apply the same general test logic to a collection of different
+parameters can use parametrized tests. For example, this:
+
+.. code-block:: python
+
+   import numpy as np
+   from ..refraction import snell
+
+
+   def test_perpendicular():
+       # For any indexes, a ray normal to the surface should not bend.
+       # We'll try a couple different combinations of indexes....
+
+       actual = snell(0, 2.00, 3.00)
+       expected = 0
+       assert actual == expected
+
+       actual = snell(0, 3.00, 2.00)
+       expected = 0
+       assert actual == expected
+
+can be rewritten as:
+
+.. code-block:: python
+
+   import numpy as np
+   import pytest
+   from ..refraction import snell
+
+
+   @pytest.mark.parametrize('n1, n2',
+                            [(2.00, 3.00),
+                             (3.00, 2.00),
+                            ])
+   def test_perpendicular(n1, n2):
+       # For any indexes, a ray normal to the surface should not bend.
+       # We'll try a couple different combinations of indexes....
+
+       actual = snell(0, n1, n2)
+       expected = 0
+       assert actual == expected
+
+The string ``'n1, n2'`` specifies which parameters this decorator will fill in.
+Pytest will run ``test_perpendicular`` twice, one for each entry in the
+list ``[(2.00, 3.00), (3.00, 2.00)]``, passing in the respective values ``n1``
+and ``n2`` as arguments.
+
+From here we refer you to the
+`pytest parametrize documentation <https://docs.pytest.org/en/latest/parametrize.html>`_.
+
+Fixtures
+--------
+
+Tests that have different logic but share the same setup code can use pytest
+fixtures. For example, this:
+
+.. code-block:: python
+
+   import numpy as np
+
+
+   def test_height():
+       # Construct a 1-dimensional Gaussian peak.
+       x = np.linspace(-10, 10, num=21)
+       sigma = 3.0
+       peak = np.exp(-(x / sigma)**2 / 2) / (sigma * np.sqrt(2 * np.pi))
+       expected = 1 / (sigma * np.sqrt(2 * np.pi))
+       # Test that the peak height is correct.
+       actual = np.max(peak)
+       assert np.allclose(actual, expected)
+
+
+   def test_nonnegative():
+       # Construct a 1-dimensional Gaussian peak.
+       x = np.linspace(-10, 10, num=20)
+       sigma = 3.0
+       peak = np.exp(-(x / sigma)**2 / 2) / (sigma * np.sqrt(2 * np.pi))
+       # Test that there are no negative values.
+       assert np.all(peak >= 0)
+
+can be written as:
+
+.. code-block:: python
+
+   import pytest
+   import numpy as np
+
+
+   @pytest.fixture
+   def peak():
+       # Construct a 1-dimensional Gaussian peak.
+       x = np.linspace(-10, 10, num=21)
+       sigma = 3.0
+       peak = np.exp(-(x / sigma)**2 / 2) / (sigma * np.sqrt(2 * np.pi))
+       return peak
+
+
+   def test_height(peak):
+       expected = 1 / (sigma * np.sqrt(2 * np.pi))
+       # Test that the peak height is correct.
+       actual = np.max(peak)
+       assert np.allclose(actual, expected)
+
+
+   def test_nonnegative(peak):
+       # Test that there are no negative values.
+       assert np.all(peak >= 0)
+
+To reuse a fixture in multiple files, add it to ``conftest.py`` located in the
+``tests/`` directory. It will automatically be imported by pytest into each
+test module.
+
+From here we refer you to the
+`pytest fixtures documentation <https://docs.pytest.org/en/latest/fixture.html>`_.
+
+Skipping Tests
+--------------
+
+Sometimes it is useful to skip specific tests under certain conditions.
+Examples:
+
+.. code-block:: python
+
+   import pytest
+   import sys
+
+
+   @pytest.mark.skipif(sys.version_info < (3, 7),
+                       reason="requires python3.7 or higher")
+   def test_something():
+       ...
+
+
+   @pytest.mark.skipif(sys.platform == 'win32',
+                       reason="does not run on windows")
+   def test_something_that_does_not_work_on_windows():
+       ...
+
+
+   def test_something_that_needs_a_special_dependency():
+       some_library = pytest.importorskip("some_library")
+       ...
+
+From here we refer you to the
+`pytest skipping documentation <https://docs.pytest.org/en/latest/skipping.html>`_.

docs/source/ci.rst

@@ -0,0 +1,63 @@
+=============================
+Continous Integration Testing
+=============================
+
+In this section you will:
+
+* Understand the benefits Continuous Integration.
+* Configure Travis-CI, a "continuous integration" service, to operate on your
+  GitHub repository.
+
+What is CI for?
+---------------
+
+If "Continuous Integration" (CI) is new to you, we refer you to
+`this excellent Software Carpentry tutorial <https://katyhuff.github.io/python-testing/08-ci/>`_
+on the subject. To summarize, CI speeds development by checking out your code on
+a fresh, clean server, installing your software, running the tests, and
+reporting the results. This helps you ensure that your code will work on your
+colleague's computer---that it doesn't accidentally depend on some local detail
+of your machine. It also creates a clear, public record of whether the tests
+passed or failed, so if things are accidentally broken (say, while you are on
+vacation) you can trace when the breaking change occurred.
+
+Travis-CI Configuration
+-----------------------
+
+The cookiecutter template has already generated a configuration file for
+Travis-CI, which is one of several CI services that are free for public
+open-source projects.
+
+.. literalinclude:: example_travis.yml
+
+You can customize this to your liking. For example, if you are migrating a
+large amount of existing code that is not compliant with PEP8, you may want to
+remove the line that does ``flake8`` style-checking.
+
+Activate Travis-CI for Your GitHub Repository
+---------------------------------------------
+
+#. Go to https://travis-ci.org and sign in with your GitHub account.
+#. You will be prompted to authorize Travis-CI to access your GitHub account.
+   Authorize it.
+#. You will be redirected to https://travis-ci.org/profile, which shows a list
+   of your GitHub repositories. If necessary, click the "Sync Account" button
+   to refresh that list.
+#. Find your new repository in the list. Click the on/off switch next to its
+   name activate Travis-CI on that repository.
+#. Click the repository name, which will direct you to the list of *builds* at
+   ``https://travis-ci.org/YOUR_GITHUB_USERNAME/YOUR_REPO_NAME/builds``. The
+   list will currently be empty. You'll see construction cones.
+#. The next time you open a pull request or push a new commit to the master
+   branch, Travis-CI will kick off a new build, and that list will update.
+
+.. note::
+
+    If this repository belongs to a GitHub *organization* (e.g.
+    http://github.com/NSLS-II) as opposed to a personal user account
+    (e.g. http://github.com/danielballan) you should follow Steps 3-5
+    above for the organization's profile at
+    ``https://travis-ci.org/profile/YOUR_GITHUB_ORGANIZATION``. It does no
+    harm to *also* activate Travis-CI for your personal fork at
+    ``https://travis-ci.org/profile``, but it's more important to activate it for
+    the upstream fork associated with the organization.