docs: 📝 split out guide into multiple pages

_quarto.yml

@@ -12,21 +12,21 @@ website:
   repo-url: "https://github.com/seedcase-project/template-python-package"
   page-navigation: true
   navbar:
-    logo: _extensions/seedcase-project/seedcase-theme/logos/seedcase/icon.svg
+    logo: "_extensions/seedcase-project/seedcase-theme/logos/seedcase/icon.svg"
     logo-alt: "Seedcase Project logo: Main page"
     pinned: true
     left:
       - text: "Overview"
         href: index.qmd
       - text: "Guide"
-        href: docs/guide.qmd
+        href: docs/guide/index.qmd
     tools:
       - icon: github
         href: "https://github.com/seedcase-project/template-python-package"
-        aria-label: "GitHub icon: Source code"
+        aria-label: "GitHub icon: Source repository"
       - icon: house
-        href: https://seedcase-project.org
-        aria-label: "House icon: Seedcase Project home page"
+        href: "https://seedcase-project.org"
+        aria-label: "House icon: Main website for the Seedcase Project"
   sidebar:
     - id: overview
       pinned: true
@@ -36,10 +36,17 @@ website:
           href: index.qmd
         - CHANGELOG.md
         - CONTRIBUTING.md
+    - id: guide
+      contents:
+        - section: "Guide"
+          href: docs/guide/index.qmd
+          contents:
+            - docs/guide/installing.qmd
+            - docs/guide/using.qmd
+            - docs/guide/updating.qmd
+            - docs/guide/next-steps.qmd
 
 format:
   seedcase-theme-html:
-    theme:
-      - brand
     include-before-body:
     - "docs/includes/site-counter.html"

docs/guide/index.qmd

@@ -0,0 +1,15 @@
+---
+title: "Guide"
+listing:
+    contents: .
+    type: grid
+    grid-columns: 1
+    sort: "order"
+    fields:
+        - title
+        - description
+---
+
+This guide gives an overview of how to use this template for creating a
+new Python package. It includes instructions for using the template and
+post-creation tasks.

docs/guide/installing.qmd

@@ -0,0 +1,46 @@
+---
+title: "Installing"
+description: |
+  Instructions for installing the required (and optional) programs to use this
+  template and create a new project from it.
+order: 1
+---
+
+There are a few programs that are required to use this template to
+create a project:
+
+- [uv](https://docs.astral.sh/uv/): A tool for managing Python
+  environments and running commands.
+- [Python](https://www.python.org/): Required by Copier, the template
+  tool.
+- [Copier](https://copier.readthedocs.io/en/stable/): A template tool
+  for making new projects in a standardised and structured way.
+- [just](https://just.systems/man/en/): A build and development
+  management tool that helps with running common build and check tasks.
+
+You can use uv to install these required programs, so
+[install](https://docs.astral.sh/uv/getting-started/installation/) that
+first. After you've installed uv, install the other programs using:
+
+```{.bash filename="Terminal"}
+uv tool install copier rust-just
+```
+
+uv will also install Python for you when you install these tools.
+
+There are some optional, though **strongly recommended**, programs to
+install and use in any project created with this template:
+
+- [Git](https://git-scm.com/): For version control and setting up Git to
+  track the newly created project.
+- [Lychee](https://lychee.cli.rs/guides/getting-started/): A link
+  checker that we include in the `justfile` for checking for broken
+  links in the files.
+- [Quarto](https://quarto.org/): A scientific and technical publishing
+  system built on Pandoc. The website built with this template is
+  created with Quarto, and the project created from this template is
+  also set up to use Quarto too.
+- [gh cli](https://cli.github.com/): For managing GitHub repositories
+  and settings from the command line. There are some post-creation steps
+  we've included that use gh to simplify setting up a GitHub repository
+  for the project.