Merge pull request #2 from ADACS-Australia/refactor/base

Documentation updates

README.md

@@ -2,32 +2,57 @@
 This template takes the effort out of starting from a good place.
 
 ## Getting Started
-***Make sure Cookiecutter is installed...***
+***Installing the needed dependencies and building your new project is easy with the following steps ...***
+
+### Make sure Cookiecutter is installed
 ``` console
 pip install cookiecutter
 ```
 *(or better yet, use [pipx](https://pypa.github.io/pipx/))*
 ``` console
 pipx install cookiecutter
 ```
-***...use it to render the project...***
+
+### Make sure Poetry is installed
+Use the official installer
 ``` console
-cookiecutter gh:ADACS-Australia/adacs_template_python_base
+curl -sSL https://install.python-poetry.org | python3 -
+```
+*(or better yet, use [pipx](https://pypa.github.io/pipx/))*
+``` console
+pipx install poetry
+```
 
+### Render the project
+Run cookiecutter on the template's repository:
+``` console
+cookiecutter gh:ADACS-Australia/adacs_template_python_base
 ```
-***...answer the questions...***
+and answer the questions:
 
 ![ADACS Python Template Questions](https://github.com/ADACS-Australia/adacs_template_python_base/blob/main/docs/assets/adacs_python_template_cookiecutter_questions.png?raw=true)
 
-***...and configure the services you need using [these instructions](https://adacs-template-python-base.readthedocs.io/en/latest/content/configuring_services.html).***
+### Install the new project
+Create and activate a new virtual environment (**use Python version >= 3.11**) using your favourite method (if you don't know how to use Python environments, we advise you to go learn about them now) and install the project by running the following in the new repo directory:
+``` console
+poetry install --all-extras
+```
+
+### Configure the services you need
+Follow [these instructions](https://adacs-template-python-base.readthedocs.io/en/latest/content/configuring_services.html) to
+configure GitHub, Read the Docs, PyPI, etc.
 
 ## What do you get for this?
 ***A codebase that eases collaboration and automatically:***
-* Ensures that all commits on the main branch and released versions build correctly and pass all unit tests
-* Enforces code formatting and linting policies
-* Manages code and release versioning
-* (optionally) publishes your code to PyPI so people can easilly install it
-* (optionally) updates, builds and publishes documentation to *Read the Docs*.
+
+* Ensures that all code on the main branch and released versions:
+    * builds correctly (including documentation) and passes all unit tests
+    * conforms to the project's code formatting and linting policies
+    * is properly versioned
+
+* And optionally, automates the following for new releases of your project:
+    * publication to [PyPI](https://pypi.org) so people can easilly install it
+    * publication of updated documentation to *Read the Docs*
 
 ***Other ADACS Python templates can then be applied to this base template to quickly kickstart a new project.***
 

docs/content/configuring_services.md

@@ -7,14 +7,19 @@ Develpers and project owners/maintainers will require accounts with one or all o
 
     To work with this codebase, you will require a *GitHub* account ([go here to get one](https://github.com)).
 
-    Branch permissions for the project repository should be configured as follows:
-
-    - Protect the main branch to only permit merges from pull requests.  This can be done by clicking on the 'branches' tab and clicking on the 'Protect this branch' button for the 'main' branch.
-    - Select 'Require status checks to pass before merging' when you set-up this branch protection rule.  This will ensure that all CI/CD tests pass before a merge to the main branch can be made.
+    Branch permissions for the main project repository should be configured only permit merges from pull requests.  To do so, navigate to `Settings->Branches->Add branch ruleset` and:
+
+    - give the Ruleset whatever name you'd like (e.g. `Protect Main`)
+    - set `Enforecement status` to `Active`
+    - add a `Target Branch` targeting criteria by pattern and type `main`
+    - select `Require a pull request before merging`
+    - select `Require status checks to pass` and add `Run all build and unit tests` from GitHub Actions as a required check
+
+    This will ensure that all CI/CD tests pass before a merge to the main branch can be made.
 
     Several secrets need to be configured by navigating to `Settings->Secrets->Actions` and adding the following:
 
-    - To host the project documentation on *Read the Docs** (see below), the following secrets need to be set (see below for where to find these values):
+    - To host the project documentation on *Read the Docs* (see below), the following secrets need to be set (see below for where to find these values):
 
         - **RTD_WEBHOOK_TOKEN**, and
         - **RTD_WEBHOOK_URL**
@@ -46,17 +51,18 @@ Develpers and project owners/maintainers will require accounts with one or all o
 
         - To obtain **RTD_WEBHOOK_URL** and **RTD_WEBHOOK_TOKEN**, migrate to the `Admin->Integrations` tab on the *RTD* project page and click on your incomming webhook.
 
-    Once properly configured, the documentation for this project should build automatically on *RTD* every time you generate a new release (see below for instructions).
+    Once properly configured, the documentation for this project should build automatically on *RTD* every time you [generate a new release](#new-release).
 
     ::: {note}
     Make sure **RTD_WEBHOOK_URL** starts with `https://`.  Prepend it if not.
     :::
 
+(config-pypi)=
 3. The [__Python Package Index (*PyPI*)__](https://pypi.org)
 
     This service is used to publish project releases.  An account is needed if you are the owner of the project, but not generally needed if you are simply a contributing developer.  An API token will need to be created and added to your *GitHub* project as **PYPI_TOKEN** (as detailed above).  This can be generated from the *PyPI* UI by navigating to `Account Settings->Add API Token`.
 
-    To test releases, a parallel account on *test.PyPI* is needed and a similar token to **PYPI_TOKEN** - named **TEST_PYPI_TOKEN** needs to be set, in the same way as above.  To create a test release, flag it as a "pre-release" through the *GitHub* interface when you generate a release, and it will be published on *test.PyPI.org* rather than *PyPI.org*.
+    To test releases, a parallel account on *test.PyPI* is needed and a similar token to **PYPI_TOKEN** - named **TEST_PYPI_TOKEN** needs to be set, in the same way as above.  To create a test release, flag it as a "pre-release" through the *GitHub* interface when you generate a release, and it will be published on *test.PyPI.org* rather than *PyPI.org*.  If this token is not defined, publication will not happen on either.
 
     ::: {note}
     Although `poetry` can be used to directly publish this project to *PyPI*, users should not do this.  The proper way to publish the project is through the *GitHub* interface, which leverages the *GitHub Workflows* of this project to ensure the enforcement of project standards before a new version can be created.

docs/content/notes_for_developers.md

@@ -1,7 +1,9 @@
-# Development Guidelines
-This section provides details on how to develop this codebase.
+# Notes for Developers
+
+This section provides details on how to configure and/or develop this codebase.
 
 ## Continuos Integration/Continuous Deployment (CI/CD) Workflow
+
 This project uses *GitHub Workflows* to automate or ease a number of development tasks.  These
 workflows can be found within the `./.github/workflows/` directory and include:
 1. **pull_request.yml**
@@ -172,9 +174,10 @@ Releases are generated through the *GitHub* UI.  A *GitHub Workflow* has been co
 4. Publish a new version of the code on [*PyPI*](https://pypi.org/).
 
 ::: {note}
-If a release is flagged as a "pre-release" through the *GitHub* interface, then documentation will not be built and the project will be published on *test.PyPI.org* instead.
+If a release is flagged as a "pre-release" through the *GitHub* interface, then documentation will not be built and the project will be published on *test.PyPI.org* (if configured; see [instructions here](#config-pypi)) instead.
 :::
 
+(new-release)=
 #### Generating a new release
 
 To generate a new release, do the following:
@@ -195,20 +198,19 @@ Documentation for this project is generated using [Sphinx](https://www.sphinx-do
     Developers are mostly spared the pain of direcly editing `.rst` files (the usual way of generating content for Sphinx) in the following ways:
 
     * default `.rst` files are generated by `sphinx-apidoc` from a [Jinja2](https://jinja.palletsprojects.com/en/latest/) template placed in the `docs/_templates` directory of the project.
-    * [MyST-Parser](https://myst-parser.readthedocs.io/en/latest/) is used to source all content from Markdown files.  MyST-Parser also offers [several optional Markdown extensions](https://myst-parser.readthedocs.io/en/latest/syntax/syntax.html) enabling the rendering of richer content (e.g. Latex equations).  Several of these extensions have been enabled by default, but not all.  These are managed with the `myst_enable_extensions` list in `docs/conf.py`.
+    * [MyST-Parser](https://myst-parser.readthedocs.io/en/latest/) is used to source all content from Markdown files.  MyST-Parser also offers [several optional Markdown extensions](https://myst-parser.readthedocs.io/en/latest/syntax/syntax.html) enabling the rendering of richer content (e.g. Latex equations).  Several of these extensions have been enabled by default, but not all.  This can be managed by editing the `myst_enable_extensions` list in `docs/conf.py`.
 
 2.  **A single point of truth for high-level aspects of the documentation**
 
-    The project `README.md` is utilised - creating a single point of truth for the main high-level aspects of the documentation - for both this documentation and all the homepages associated with the services used by this project.
+    The project `README.md` is utilised, creating a single point of truth for the main high-level aspects of the documentation for both this documentation and all the homepages associated with the services used by this project (see above).
 
-3. **As much content as possible is generated from the code itself**
-
-    *sphinx-apidoc* is used to harvest as much content about the project as possible from the codebase's docstrings.  This content is placed is the `_apidoc` directory and is used to populate the
-    following sections of the documentation:
+    ::: {note}
+    *MyST-Parser* directives will not render properly on *GitHub*.  Similarly: *GitHub* Markdown directives will not work on *Read The Docs*.
+    :::
 
-    a. _CLI Documentation_, generated automatically from any *Click*-based CLI applications that are part of the project,
+3. **As much content as possible is generated from the code itself**
 
-    b. _API Documentation_, generated by `spinx-autodoc` from the docstrings of the project's Python code,
+    `sphinx-autodoc` is used to extract documentation from the docstrings in your codebase.
 
 #### Generating the Documentation
 
@@ -239,10 +241,16 @@ The majority of documentation changes can be managed in one of the following 4 w
 
 	Examine the Markdown files in the `docs/content` directory.  Does the content that you want to add fit naturally within one of those files?  If so: add it there.
 
-4. **Add a new Markdown file to the `docs` directory**:
+4. **Add a new Markdown file**:
+
+	Otherwise, create a new `.md` file in the `docs/content` directory and add it to the list of Markdown files referenced in `docs/index.rst`.  Note that these files will be added to the documentation in the order specified, so place it in that list where you want it to appear in the final documentation.  This new `.md` file should start with a top-level title (marked-up by starting a line with a single `#`; see the top of this file for an example).
 
-	Otherwise, create a new `.md` file in the `docs/content` directory and add it to the list of Markdown files listed in the `docs/index.rst`.  Note that files are added to the documentation in the order specified, so place it in that list where you want it to appear.  This new `.md` file should start with a top-level title (marked-up by starting a line with a single `#`; see the top of this file for an example).
+5. **Extend the MyST-Parser support***
+
+    New MyST-Parser extensions can be enabled in `docs/conf.py` by extending the `myst_enable_extensions` list.  See the
+    MyST-Parser documentation for a list of available extensions and instructions on how to use them.
 
 #### Adding images, etc.
 
 While not strictly required, it is best practice to place any images, plots, etc. used in the documentation in the `docs/assets` directory.
+

{{cookiecutter.repo_name}}/INSTRUCTIONS.template

@@ -2,54 +2,60 @@
 // Once this new project is configured, you can delete this file.  See 'notes_for_developers' if you need to see this content again.
 //
 
-*Now that your template has been rendered, we recommend configuring it as follows (more detailed instructions can be found at `https://adacs-python-template.readthedocs.io/en/latest/content/configuring_services.html`):*
+*Now that your template has been rendered, we recommend configuring it as follows:*
 
-1. **Create a GitHub repo**
+1. **Create a Python environment**
 
-Goto *`https://github.com`* and create a new repo with the following:
-
-- account:   **{{cookiecutter.github_login}}**
-- repo name: **{{cookiecutter.repo_name}}**
+Use your favourite method to create and activate a Python environment for your development.
 
-2. **Enable GitHub Actions write permissions**
+2. **Install the project and all dependencies**
 
-On Github, navigate within the repo to `Settings->Actions->General` and select `Read and write permissions`.  This needs to be done
-before the next stage so that the GitHub version bump action that is run on first upload does not fail.
+With your environment activated, run the following from within your new repo: `poetry install --all-extras`
 
-3. **Push the local repo to GitHub**
+***NOTE: This needs to be done before any tests can be run, documentation built, etc.***
 
-Run the following from within your new local repo: `git push -u origin main`
+3. **Create a GitHub repo**
 
-4. **Configure main branch permissions**
+Goto *`https://github.com`* and create a new repo with the following:
 
-Navigate to `Settings->Branches->Add branch protection rule` and ...
+- account:   **{{cookiecutter.github_login}}**
+- repo name: **{{cookiecutter.repo_name}}**
 
-- type *main* in the `Branch name pattern`
-- select `Require a pull request before merging`
-- select `Require status checks to pass before merging`
+4. **Enable GitHub Actions write permissions**
 
-5. **[Optional] Configure repository secrets**
+On Github, navigate within the repo to `Settings->Actions->General` and select `Read and write permissions`.
 
-*This can be done at any time when you want to enable these features; they are simply deactivated until you do; see *`https://adacs-python-template.readthedocs.io/en/latest/content/configuring_services.html`* for an account of where to find these values.*
+***NOTE: This needs to be done before the next stage so that the GitHub version bump action that is run on first upload does not fail.***
 
-Navigate to `Settings->Secrets->Actions` and add the following *Secrets*:
+5. **Push the local repo to GitHub**
 
-- **RTD_WEBHOOK_TOKEN** and **RTD_WEBHOOK_URL** enable automated hosting of documentation on *Read the Docs*
-- **PYPI_TOKEN** &/or **TEST_PYPI_TOKEN** enable the publication of code releases on the *Python Package Index* &/or the *Test Python Package Index* respectively
+Your new repo has been configured with your GitHub repo details.  Run the following from within your new local repo to push it to GitHub: `git push -u origin main`
 
-6. **Create a Python environment**
+6. **Configure branch permissions**
 
-Use your favourite method to create and activate a Python environment for your development.
+Navigate to `Settings->Branches->Add branch ruleset` and ...
 
-7. **Install the development dependencies**
+- give the Ruleset whatever name you'd like (e.g. `Protect Main`)
+- set `Enforecement status` to `Active`
+- add a `Target Branch` targeting criteria by pattern and type `main`
+- select `Require a pull request before merging`
+- select `Require status checks to pass` and add `Run all build and unit tests` from GitHub Actions as a required check
 
-From within the repo, run the following: `poetry install --all-extras`
+***From this point on, no development should be performed on the main branch.  All updates to the main branch are managed via Pull
+Requests in the GitHub UI.***
 
-8. **Activate pre-commit git hooks**
+7. **[Optional] Activate pre-commit git hooks**
 
 From within the repo, run the following: `pre-commit install`
 
+8 **[Optional] Configure Services (Read The Docs, PyPI, etc.)**
+
+This can be done at any time when you want to enable these features; they are simply deactivated until you do; see *`https://adacs-python-template.readthedocs.io/en/latest/content/configuring_services.html`* for instructions.
+
 9. **Start developing!**
 
+No development should be done on *main*, so create and checkout a new git branch with `git checkout -b new_branch_name` and start
+developing.
+
 If you have any questions, consult the template documentation at *`https://adacs-python-template.readthedocs.io/en/latest/index.html`*.
 

{{cookiecutter.repo_name}}/docs/content/getting_started.md

@@ -6,10 +6,7 @@ $ pip install {{ cookiecutter.__package_name }}
 ```
 
 ::: {note}
-This section is intended to be a place where you can show how easy it is to use your package.
-Taylor it to your own needs and see the *Markup Tips* section at the end for some guidance on
-the extended markdown elements that the Myst Parser gives you that you can use to build
-content.
+This section is intended to be a place where you can show how great your project is and how easy easy it is to use.  Taylor it to your own needs and see the *Markup Tips* section below for some guidance on the extended markdown elements that the Myst Parser gives you for building content.
 :::
 
 ## Markup Tips