Documentation tweaks (#134)

Author: coretl

README.md

@@ -43,7 +43,7 @@ Visit <https://dev-portal.diamond.ac.uk/create> and you will see a list of templ
 
 ## Create a new project from the commandline
 
-You will need to `pip install copier` inside an activated `venv`, then you can create a new module via:
+You will need to `pip install copier` inside an activated `venv` from python3.8 or later, then you can create a new module via:
 
 ```
 mkdir /path/to/my-project

copier.yml

@@ -1,7 +1,9 @@
 # Project Details
 package_name:
     type: str
-    help: Name of the python import package
+    help: |
+        Name of the python import package. 
+        Must be a valid python identifier, i.e. my_package
     validator: >-
         {% if not (package_name | regex_search('^[a-zA-Z][a-zA-Z_0-9]+$')) %}
         {{package_name}} is not a valid python package name
@@ -29,7 +31,9 @@ github_org:
 
 repo_name:
     type: str
-    help: Name of the repository
+    help: |
+        Name of the repository.
+        Generally the package name with underscores replaced by dashes.
     default: "{{ package_name | replace('_', '-') }}"
     validator: >-
         {% if not (repo_name | regex_search('^[a-zA-Z][a-zA-Z_\\.\\-0-9]+$')) %}
@@ -40,7 +44,8 @@ distribution_name:
     type: str
     help: |
         Name of the python distribution package that will be created.
-        This is what people will `pip install`
+        This is what people will `pip install`.
+        Generally the same as the repo name unless there is a name clash on PyPI.
     default: "{{ repo_name }}"
 
 author_name:

docs/how-to/dev-install.md

@@ -22,6 +22,8 @@ pip install -e '.[dev]'
 :::
 
 :::{tab-item} VSCode devcontainer
+If you are at DLS, then first [setup podman and its fix for devcontainer features](https://dev-portal.diamond.ac.uk/guide/containers/tutorials/podman/#enable-use-of-vscode-features)
+
 ```
 code .
 # Click on 'Reopen in Container' when prompted

docs/tutorials/create-new.md

@@ -4,24 +4,35 @@ Once you have followed the [](./installation) tutorial, you can use `copier` to
 
 ```
 $ mkdir /path/to/my-project
-$ copier copy gh:DiamondLightSource/python-copier-template /path/to/my-project
+$ copier copy --trust gh:DiamondLightSource/python-copier-template /path/to/my-project
 ```
 
 This will:
 
 - Ask some questions about the project to be created
 - Expand the template with the answers give
 - Record the answers in the project so they can be used in later updates
+- Create a git repository if the directory is not already one
+
+## Committing the results
+
+You can now check what the template has created, tweak the results if desired, and commit the results:
+```
+$ cd /path/to/my-project
+$ git add .
+$ git commit -m "Expand from python-copier-template x.x.x"
+```
 
 ## Uploading to GitHub
 
 You can now [create a new blank project on GitHub](https://github.com/new). Choose the same GitHub owner and repo name that you answered in the questions earlier. GitHub will now give you the commands needed to upload your repo from GitHub
 
-## Setings
+## Settings
+
+You can now go to the cogwheel on the main page next to the "About" header, and set the project description to match the answer you gave.
 
-You can now go to the `Settings` and set:
+Then go to the `Settings` tab and set:
 
-- The project description to match the answer you gave
 - Enable Pages if you chose to use sphinx for your documentation
 
 ## Getting started with your new repo