packaging and doc updates

.github/CODEOWNERS

@@ -1,3 +1,3 @@
 # automatically requests pull request reviews for files matching the given pattern; the last match takes precendence
 
-*   @sosey
+*   @sosey    @Roman-Supernova-PIT/software-admins

.github/workflows/dependabot.yml

@@ -1,3 +1,4 @@
+name: "Dependabot Checks"
 version: 2
 updates:
 
@@ -9,7 +10,7 @@ updates:
     interval: weekly
   open-pull-requests-limit: 10
   reviewers:
-    - "sosey"
+    - "Roman-Supernova-PIT/software-admins"
   allow:
     - dependency-type: direct
     - dependency-type: indirect

.github/workflows/sphinx-deploy.yml

@@ -1,4 +1,4 @@
-name: "Deploy Sphinx documentation to Pages"
+name: "Deploy Sphinx Package Documentation to Pages"
 
 on:
   push:

.github/workflows/tests.yml

@@ -12,7 +12,7 @@ concurrency:
 
 jobs:
   test:
-    uses: OpenAstronomy/github-actions-workflows/.github/workflows/tox.yml@v1
+    uses: OpenAstronomy/github-actions-workflows/.github/workflows/tox.yml@924441154cf3053034c6513d5e06c69d262fb9a6  # v1.13.0
     with:
       envs: |
         - linux: py311-test

README.rst

@@ -2,3 +2,42 @@ Roman Supernova PIT Packaging Guide
 ===================================
 
 The `Roman Supernova PIT Python Packaging Guide <https://Roman-Supernova-PIT.github.io/package-template/>`__ is based on the OpenAstronomy package and contains an embedded `cookiecutter <https://cookiecutter.readthedocs.io/>`__ template.
+
+
+Using the Template
+==================
+
+With this template and guide is a `cookiecutter <https://cookiecutter.readthedocs.io/>`__ template which allows you to get started quickly with a package as described in this guide.
+
+To create a new package based on the template run:
+
+.. code-block:: console
+
+   $ pip install cookiecutter cruft
+   $ cruft create https://github.com/Roman-Supernova-PIT/package-template
+
+and go through the steps offered in the cli naming your package and filling in your details.
+Cruft is built on cookiecutter, and enables the updating of the template from the source.
+This takes the form of pull requests to the repository that the new package is pushed to.
+If a package already has a cookiecutter template, it can be linked to the parent repository using ``cruft link url-to-template``.
+
+To manually check whether the current environment matches with the template then ``cruft check`` will tell you what the current status is.
+``cruft update`` will manually trigger an updating of the package to the template.
+
+If you would like to stick to simply the cookiecutter approach, the template still supports that functionality thusly:
+
+.. code-block:: console
+
+   $ pip install cookiecutter
+   $ cookiecutter gh:Roman-Supernova-PIT/package-template -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, 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.
+The template currently implements the following optional flags, all of which default to off:
+
+* ``include_example_code``: This option will fill your new package with some example functions to allow you to test it.
+* ``use_compiled_extensions``: This turns on the features needed to support compiled extensions as described in :ref:`extensions`.
+* ``enable_dynamic_dev_versions``: This enables a feature which ensures that ``my_package.__version__`` always returns the current git version as calculated by ``setuptools_scm`` when the package is installed as an editable install. See :ref:`dev-versions` for more details.

docs/advanced/versioning.rst

@@ -10,7 +10,8 @@ complex.
 We strongly recommend using `setuptools_scm <https://github.com/pypa/setuptools_scm>`__ to do this.
 With a little effort and understanding it is possible to make the git history
 the single source of truth for all your version information, for your releases
-and any development installs.
+and any development installs. Using setuptools_scm is part of the default choices in the package
+template and will be active unless you choose otherwise.
 
 .. _setuptools-scm:
 

docs/ci.rst

@@ -11,7 +11,8 @@ Workflows can be set to begin on triggers for example, a ``git push`` or a new t
 
 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.
+Open Astronomy maintains a `set of tools <https://github.com/OpenAstronomy/github-actions-workflow>`__ to make configuring GitHub Actions easier. A `free course <https://github.com/skills/hello-github-actions>`__ for GitHub Actions is available.
+
 
 Examples
 ++++++++

docs/conf.py

@@ -54,6 +54,25 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-# html_static_path = ['_static']
 
 master_doc = 'index'
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+html_theme = "alabaster"
+html_static_path = ['_static']
+html_sidebars = {
+    '**': [
+        'about.html',
+        'navigation.html',
+        'relations.html',
+        'searchbox.html',
+    ]
+}
+html_theme_options = {
+    'fixed_sidebar': True,
+    'logo': "logo_black_filled.png",
+    'logo_text_align': "left",
+    'sidebar_width':'250px',
+    'show_relbars':True,
+}

docs/minimal.rst

@@ -26,13 +26,12 @@ these files in turn.
 Assuming that you are planning to make your package open source, the most
 important file you will need to add to your package is an open source license.
 Many packages in the scientific Python ecosystem use the `3-clause BSD license
-<https://opensource.org/licenses/BSD-3-Clause>`_ and we recommend following
-this or using the `MIT license <https://opensource.org/licenses/MIT>`_
-unless you have a good reason not to.
+<https://opensource.org/licenses/BSD-3-Clause>`_ and the packages maintained by
+the Roman Supernova PIT group will too. If you have a good reason not to, please
+contact one of the software admins for the PIT.
 
-To include the license in your package, create a file called LICENSE
-and paste the license text into it, making sure that you update the
-copyright year, authors, and any other required fields
+The BSD 3-Clause license is included as part of the package template and will
+be created when you generate a new package.
 
 .. _readme:
 
@@ -44,8 +43,7 @@ what the package is, and either gives some information about how to install/use
 it or links to more extensive documentation. We recommend using the
 `reStructuredText (rst) <http://docutils.sourceforge.net/rst.html>`_ format for
 your README as this will ensure that the README gets rendered well online, e.g.
-on `GitHub <https://github.com>`_ or `GitLab <https://gitlab.com>`_ and on `PyPI
-<https://pypi.org>`_.
+on `GitHub <https://github.com>`_ or  `PyPI <https://pypi.org>`_.
 
 .. _package_init:
 

{{ cookiecutter.package_name }}/.github/CODEOWNERS

@@ -1,3 +1,3 @@
 # automatically requests pull request reviews for files matching the given pattern; the last match takes precendence
 
-*       @{{ cookiecutter.github_username }} 
+*       @{{ cookiecutter.github_username }} @Roman-Supernova-Pit/software-admins

{{ cookiecutter.package_name }}/.github/ISSUE_TEMPLATE/FEATURE_REQUEST.md

@@ -0,0 +1,21 @@
+---
+name: "Feature request"
+about: Suggest an idea for this project
+title: "[New Feature]: "
+labels: enhancement, needs triage
+assignees: ''
+---
+
+## Is your feature request related to a problem? Please describe.
+<!--A clear and concise description of what the problem is. 
+Ex. I'm always frustrated when [...] -->
+
+## Describe the solution you'd like
+<!--A clear and concise description of what you want to happen.-->
+
+## Describe alternatives you've considered
+<!--A clear and concise description of any alternative solutions or features you've considered.-->
+
+## Additional context
+<!--Add any other context or screenshots about the feature request here.-->
+

{{ cookiecutter.package_name }}/.github/ISSUE_TEMPLATE/ISSUE_TEMPLATE.md

@@ -0,0 +1,47 @@
+---
+name: "🐞 Issue report for {{ cookiecutter.package_name }}"
+about: Create a report describing unexpected or incorrect behavior.
+title: "[Issue]: <title>"
+labels: bug
+assignees: ''
+---
+
+<!--
+Thanks for taking the time to fill out this report!
+Please have a search on our repository to see if a similar
+issue has already been posted. If a similar issue is closed, have a
+quick look to see if you are satisfied by the resolution.
+
+If not please go ahead and open an issue!
+-->
+
+### Current Behavior:
+<!-- A concise description of what you're experiencing. -->
+
+### Expected Behavior:
+<!-- A concise description of what you expected to happen. -->
+
+### Steps To Reproduce:
+<!--
+Example: steps to reproduce the behavior:
+1. In this environment...
+1. With this config...
+1. Run '...'
+1. See error...
+-->
+
+### Environment:
+<!--
+Example:
+- OS: Ubuntu 20.04
+- Node: 13.14.0
+- npm: 7.6.3
+- python: 3.13
+- numpy: 2.0
+-->
+
+### Anything else:
+<!--
+Links? References? Anything that will give us more context about the issue that you are encountering!
+-->
+

{{ cookiecutter.package_name }}/.github/PR_TEMPLATE.md → {{ cookiecutter.package_name }}/.github/ISSUE_TEMPLATE/PR_TEMPLATE.md

@@ -1,20 +1,39 @@
-<!-- If this PR closes a GitHub issue, reference it here by its number -->
-Closes #
+---
+name: "Pull Request for {{ cookiecutter.package_name }}"
+about: Create a pull request to submit new or updated code to the repository
+title: "[PR]: "
+labels: possible solution
+assignees: ''
+---
+## What type of PR is this? (check all applicable)
+
+- [ ] Refactor
+- [ ] Feature
+- [ ] Bug Fix
+- [ ] Optimization
+- [ ] Documentation Update
+- [ ] Have you followed the guidelines in our Contributing document?
+- [ ] Have you checked to ensure there aren't other open [Pull Requests](../../../pulls) for the same update/change?
 
 <!-- describe the changes included with this PR here -->
 This PR addresses ...
 
+<!-- If this PR closes a GitHub issue, reference it here by its number -->
+Closes #
+
+
 <!-- if you can't perform these tasks due to permissions, please ask a maintainer to do them -->
 ## Tasks
 - [ ] **request a review from someone specific**, to avoid making the maintainers review every PR
 - [ ] Does this PR change user-facing code / API? (if not, label with `no-changelog-entry-needed`)
-  - [ ] write news fragment(s) in `changes/`: `echo "changed something" > changes/<PR#>.<changetype>.rst` (see below for change types) 
+  - [ ] write news fragment(s) in `changes/`: `echo "changed something" > changes/<PR#>.<changetype>.rst` (see expansion below for change types) 
   - [ ] update or add relevant tests
   - [ ] update relevant docstrings and / or `docs/` page
     - [ ] Do truth files need to be updated?
 
+
 <details><summary>news fragment change types...</summary>
 
 - ``changes/<PR#>.general.rst``: infrastructure or miscellaneous change
-- ``changes/<PR#>.docs.rst``
+- ``changes/<PR#>.docs.rst``: updates for documentation
 </details>

{{ cookiecutter.package_name }}/.github/workflows/labeler.yml

@@ -27,7 +27,7 @@ documentation:
       - 'docs/**/*'
       - '*.md'
       - '.readthedocs.yaml'
-      - 'LICENSE'
+      - 'licenses/LICENSE.rst'
 
 installation:
   - changed-files: