Merge pull request #9 from ADACS-Australia/feature/docker

Documentation improvements.

README.md

@@ -1,5 +1,22 @@
-# Starting a new Python codebase?
-This template takes the effort out of starting from a good place.
+<p align="center">
+  <img src="https://github.com/ADACS-Australia/adacs_template_python_base/blob/main/docs/assets/adacs_logo.png" alt="ADACS Logo">
+</p>
+
+<p align="center">
+  <a href="https://www.python.org/downloads/release/python-311/">
+    <img src="https://img.shields.io/badge/python-3.11-blue.svg" alt="Python 3.11">
+  </a>
+  <a href='https://adacs-base-python-template.readthedocs.io/en/latest/?badge=latest'>
+    <img src='https://readthedocs.org/projects/adacs-base-python-template/badge/?version=latest' alt='Documentation Status' />
+  </a>
+  <a href="https://opensource.org/licenses/MIT">
+    <img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="MIT License">
+  </a>
+</p>
+
+# Base Python Codebase Template
+
+**Starting a new Python codebase?**  Read on to see how this template can have you set-up with all the elements of a professional codebase in less than 30 mins.
 
 ## Getting Started
 ***Installing the needed dependencies and building your new project is easy with the following steps ...***

docs/content/common_gotchas.md

@@ -0,0 +1,23 @@
+# Common Gotchas
+
+If you are encountering problems with a codebase rendered from this template, perhaps one of the
+following is happening:
+
+## Configuring PyPI and TestPyPI
+
+### **'Entire account'-scoped secrets**
+
+'Entire account'-scoped tokens for *PyPI* (and *TestPyPI*) are not ideal, but there is a cold start problem when adding new projects to your account: you need a token to add a new project, but you need a project to create a project-scoped token.  For this reason, you need to create and configure GitHub with a temporary 'Entire account'-scoped token first, and then when you have added the project to *PyPI* and *TestPyPi*, you need to delete the temporary token and repeat the process: create a token scoped to the project and reconfigure *GitHub* with the new secret.  **It's easy to forget to do this.**
+
+## Workflow Issues
+
+### **My checks keep failing**
+
+Have you given workflows write permissions?  If not, navigate within the repo to `Settings->Actions->General` and select `Read and write permissions`.
+
+## Developing Documentation
+
+### **I've added a new markdown file to the `docs/content` directory, but it isn't showing-up in the final rendered documentation**
+
+Have you added it to the `docs/index.rst` file?  Follow the examples there for adding your new content
+to the documentation.

docs/index.rst

@@ -11,4 +11,5 @@
    Home <self>
    Configuring a new project <content/configuring_services>
    Development guidelines <content/development_guidelines>
+   Common Gotchas <content/common_gotchas>
    Maintianing this template <content/template_maintenance>

{{cookiecutter.repo_name}}/INSTRUCTIONS.template

@@ -6,57 +6,63 @@
 
 1. **Create and activate a Python 3.11 environment**
 
-Use your favourite method to create and activate a Python 3.11 environment for your development.
+Use your favourite method to *create and activate* a Python 3.11 environment for your development.
 
 2. **Install the project and all dependencies**
 
 With your environment activated, run the following from within your new repo: `poetry install`
 
 *NOTE: This needs to be done before any tests can be run, documentation built, etc.*
 
-3. **Create a GitHub repo and adjust workflow permissions**
+3. **Create a GitHub repo**
 
-Goto *`https://github.com`* and create a new repo with the following:
+If you have not yet done so, goto *`https://github.com`* and create a new repo with the following:
 
 - account:   **{{cookiecutter.github_login}}**
 - repo name: **{{cookiecutter.repo_name}}**
 
+4. **Adjust workflow permissions**
+
 Navigate within the repo to `Settings->Actions->General` and select `Read and write permissions`.
 
 *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.*
 
-4. **Push the local repo to GitHub**
+5. **Push the local repo to GitHub**
 
 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`
 
 *NOTE: If you notice any failed workflow runs at this point, it may be because you forgot to make the Action permission change mentioned above.*
 
-5. **Configure branch permissions**
+6. **Configure branch permissions**
 
 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 the check `Run all build and unit tests` as a required check
+- add a `Target Branch` via `Add target->Include by pattern` and type `main`
+- adjust `Branch Rules` by selecting `Require a pull request before merging`
+- adjust `Branch Rules` by selecting `Require status checks to pass` and add the check `Run all build and unit tests` as a required check
 - push the `Create` button at the bottom
 
 *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.*
 
-6. **[Optional] Activate pre-commit git hooks**
+7. **[Optional] Activate pre-commit git hooks**
 
 From within the repo, run the following: `pre-commit install`
 
-7 **[Optional] Configure Services (Read The Docs, PyPI, etc.)**
+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!**
 
-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.
+No development should be done on the *main* branch, so create and checkout a new git branch with `git checkout -b new_branch_name` and start developing.
 
-8. **Start developing!**
+**N.B.: If you are new to the use of this template, make sure you have a good read of the following
+sections of the documentation:**
 
-**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.
+- `Guidelines for Developing a New Project`: *https://adacs-base-python-template.readthedocs.io/en/latest/content/development_guidelines.html*
+- `Common Gotchas`: *https://adacs-base-python-template.readthedocs.io/en/latest/content/common_gotchas.html*
 
-**N.B.: If you are new to the use of this template, make sure you have a good read of the `Notes for Developer
-If you have any questions, consult the template documentation at *`https://adacs-python-template.readthedocs.io/en/latest/index.html`*.
+Any questions?  Consult the docs at *https://adacs-base-python-template.readthedocs.io/en/latest/index.html*.