Ci docs (#43)

* Adding workflow actions documentation * Update docs/ci.rst Co-authored-by: Stuart Mumford <stuart@cadair.com> * Update docs/ci.rst Co-authored-by: Stuart Mumford <stuart@cadair.com> * Update docs/ci.rst Co-authored-by: Stuart Mumford <stuart@cadair.com> * Update docs/ci.rst Co-authored-by: Stuart Mumford <stuart@cadair.com> * Update docs/ci.rst Co-authored-by: Stuart Mumford <stuart@cadair.com> * Update docs/ci.rst Co-authored-by: Stuart Mumford <stuart@cadair.com> * Update docs/ci.rst Co-authored-by: Stuart Mumford <stuart@cadair.com> * Update docs/ci.rst Co-authored-by: Stuart Mumford <stuart@cadair.com> * Update docs/ci.rst Co-authored-by: Stuart Mumford <stuart@cadair.com> * Update docs/ci.rst Co-authored-by: Stuart Mumford <stuart@cadair.com> * Update docs/ci.rst Co-authored-by: Stuart Mumford <stuart@cadair.com> * Update docs/ci.rst Co-authored-by: Stuart Mumford <stuart@cadair.com> * Update docs/ci.rst Co-authored-by: Stuart Mumford <stuart@cadair.com> * Update docs/ci.rst Co-authored-by: Stuart Mumford <stuart@cadair.com> * Update docs/ci.rst Co-authored-by: Stuart Mumford <stuart@cadair.com> * ci.rst indent fix * ci.rst indent fix --------- Co-authored-by: Stuart Mumford <stuart@cadair.com>
OpenAstronomy · Jan 29, 2024 · d32d742 · d32d742
1 parent 9f1c8ac
commit d32d742
Show file tree

Hide file tree

Showing 4 changed files with 149 additions and 5 deletions.
diff --git a/docs/ci.rst b/docs/ci.rst
@@ -1,6 +1,149 @@
 .. _ci:
 
+======================
 Continuous Integration
 ======================
 
-Needs writing!
+Continuous Integration (CI) is the method by which software is tested and built before deployment to users.
+A set of 'jobs' are defined in a ``.yml`` file, roughly taking the flow build - test - deploy.
+Each run is built from a clean environment.
+Workflows can be set to begin on triggers for example, a ``git push`` or a new tag.
+
+There are an array solutions for running CI, Open Astronomy recommends `GitHub Actions <https://docs.github.com/en/actions/>`__ for projects using GitHub.
+GitHub Actions workflows are defined in the ``.github/workflows/`` folder at the root of the repo.
+Open Astronomy maintains a `set of tools <https://github.com/OpenAstronomy/github-actions-workflow>`__ to make configuring GitHub Actions easier.
+
+Examples
+++++++++
+Testing
+-------
+In order GitHub Actions to run your workflow, it requires; an event to trigger the workflow, one or more jobs to complete and all steps must either run a script or trigger an action.
+Looking at this in context:
+
+.. code-block:: yaml
+
+    name: Run template tests
+
+    on:
+      push:
+      pull_request:
+      workflow_dispatch:
+
+    jobs:
+      test:
+        uses: OpenAstronomy/github-actions-workflows/.github/workflows/tox.yml@v1
+        with:
+          envs: |
+            - linux: py311-test
+
+In this case the workflow is triggered on a push to a branch, a PR, or a manual trigger of the workflow (`workflow_dispatch`).
+The second line of the job defines the name of the job, in this case ``test``, and uses Open Astronomy's pre-defined workflow to run the tests with tox.
+The ``envs`` list, defines which tox environments will be run for that job.
+
+Publishing to PyPI
+------------------
+
+No Compiled Extensions
+######################
+
+Python packages should be published on `PyPI <https://pypi.org/>`__, which can be automated on CI.
+This can improve security (as fewer people need access to publish on PyPI) and make it less effort for maintainers to publish a release.
+When we are building and publishing releases to PyPI we only want this to happen on a `git tag <https://git-scm.com/book/en/v2/Git-Basics-Tagging>`__, as opposed to on every commit.
+However, if we only run the build job on tags, we never have a way to test that the job works before we tag a release of our package.
+The OpenAstronomy publish workflows will (by default) only publish to PyPI on a tag which starts with `v` (`see here <https://github-actions-workflows.openastronomy.org/en/stable/publish.html#upload-to-pypi>`__).
+Therefore, we recommend running the workflow on both push to your default branch (`main`), on tags and on manual runs.
+
+.. code-block:: yaml
+
+    on:
+      push:
+        branches:
+          - 'main'
+      tag:
+      workflow_dispatch:
+
+   jobs:
+     publish:
+       uses: OpenAstronomy/github-actions-workflows/.github/workflows/publish_pure_python.yml@v1
+       with:
+         test_extras: test
+         test_command: pytest --pyargs <package name>
+     secrets:
+       pypi_token: ${{ secrets.pypi_token }}
+
+Replace references to `<package_name>` with the package to be published.
+
+To publish to PyPI we need a PyPI token, associated with your PyPI account.
+`Instructions on creating up your key here <https://pypi.org/help/#apitoken>`__.
+The secret can be stored at `organisation <https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions#creating-secrets-for-an-organization>`__ or `repo level <https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions#creating-secrets-for-a-repository>`__ in GitHub settings.
+
+With Compiled Extensions
+########################
+
+Almost all packages on pypi also have environment specific binaries with all dependencies packaged.
+It is expected that a package publishes both a pure python distribution and the binary, see `here for examples <https://pypi.org/project/sunpy/#files>`__.
+
+In this case, in addition to the running the tests, the ``with`` block also includes targets.
+'Targets' are the distributions which the binary will be built for, so in this case it would be linux and MacOS 64 bit.
+The ``publish`` method from the Open Astronomy GitHub actions packages the module with the dependencies for the specific targets listed
+
+.. code-block:: yaml
+
+    jobs:
+      publish:
+        uses: OpenAstronomy/github-actions-workflows/.github/workflows/publish.yml@v1
+        with:
+          test_extras: test
+          test_command: pytest --pyargs test_package
+          targets: |
+            - linux
+            - cp3?-macosx_x86_64
+      secrets:
+        pypi_token: ${{ secrets.pypi_token }}
+
+
+.. sam, work your way to the full example use the sunkit example
+.. https://github.com/sunpy/sunkit-instruments/blob/main/.github/workflows/ci.yml
+
+Putting it all together
+#######################
+
+Combining the above steps reveals a total workflow, build, testing and publishing
+
+.. code-block:: yaml
+
+    name: package_deployment
+
+    on:
+      push:
+      tag:
+
+    jobs:
+      test:
+        uses: OpenAstronomy/github-actions-workflows/.github/workflows/tox.yml@v1
+        with:
+          envs: |
+            - linux: py311
+
+      publish_python:
+        uses: OpenAstronomy/github-actions-workflows/.github/workflows/publish_pure_python.yml@v1
+          with:
+            test_extras: test
+            test_command: pytest --pyargs test_package
+        secrets:
+          pypi_token: ${{ secrets.pypi_token }}
+
+      publish_binaries:
+       publish:
+         uses: OpenAstronomy/github-actions-workflows/.github/workflows/publish.yml@v1
+         with:
+           test_extras: test
+           test_command: pytest --pyargs test_package
+           targets: |
+             - linux
+             - cp3?-macosx_x86_64
+       secrets:
+         pypi_token: ${{ secrets.pypi_token }}
+
+The ``.github/workflows/`` directory may contain several workflows such as the above.
+Each file may contain different workflows, with different triggers dependent on requirements.
diff --git a/docs/data.rst b/docs/data.rst
@@ -5,6 +5,7 @@ Including data in your package
 
 Using ``setuptools_scm`` to link your Python package to your git repository also makes including data easy.
 By setting ``include_package_data = true`` in the ``[tool.setuptools]`` section of ``pyproject.toml``, ``setuptools_scm`` will automatically include all files tracked by git in your package.
+
 While this is useful for including required non-Python files, it's pretty common to have files that don't belong in your distribution in your git repository, such as continuious integration configurations, or even git config files.
 It's possible to exclude certain files and directories which are tracked by git from being included in your built package by adding ``exclude`` or ``prune`` lines to the ``MANIFEST.in`` file in the root of the repository.
 An example ``MANIFIEST.in`` file might look like::

diff --git a/docs/docs.rst b/docs/docs.rst
@@ -120,9 +120,9 @@ mentioned in ``dependencies``):
 
     [project.optional-dependencies]
     docs = [
-        sphinx
-        sphinx-automodapi
-        numpydoc
+        "sphinx",
+        "sphinx-automodapi",
+        "numpydoc",
     ]
 
 This will then allow contributors to type::

diff --git a/docs/index.rst b/docs/index.rst
@@ -45,7 +45,7 @@ If you would like to stick to simply the cookiecutter approach, the template sti
    $ cookiecutter gh:OpenAstronomy/packaging-guide -o ./output_directory
 
 This will create a new directory in your current directory named the same as the value of "packagename" you supplied.
-Change into this directory and run ``git init`` to make it into a git repository.
+Change into this directory and run ``git init`` to make it into a git repository, and make an initial commit.
 This is required in order to have software versioning working for your package.
 
 The goal of the template is to quickly get you setup with the files described in the guide.