Update documentation and improve reference links

Refactored documentation to correct and update API references from `configurations` to `models` for accuracy. Introduced a new CLI documentation file and adjusted formatting in tutorials for better readability. Added HTML comment markers in `README.md` for improved structure.
callowayproject · Dec 24, 2024 · 7d48f18 · 7d48f18
1 parent d3ae1aa
commit 7d48f18
Show file tree

Hide file tree

Showing 6 changed files with 105 additions and 78 deletions.
diff --git a/README.md b/README.md
@@ -10,6 +10,8 @@
 (https://github.com/callowayproject/project-forge/workflows/CI/badge.svg)]
 (https://github.com/callowayproject/project-forge/actions)
 
+<!--start-->
+
 Project Forge is a composable project scaffolding tool.
 Developers can quickly generate new projects by only answering a few questions.
 
@@ -60,3 +62,5 @@ It includes configuration and instructions only.
 Each _overlay_ references a pattern and how to configure it for the composition,
 like "Hamburger, well done, placed between buns."
 A task performs an action during project generation, like "stir for 3 minutes."
+
+<!--end-->
diff --git a/docs/cli.md b/docs/cli.md
@@ -0,0 +1,8 @@
+# Command-line interface
+
+::: mkdocs-click
+:module: project_forge.cli
+:command: cli
+:prog_name: project-forge
+:style: table
+:depth: 1
diff --git a/docs/reference/composition.md b/docs/reference/composition.md
@@ -1,6 +1,6 @@
 # Composition
 
-A [composition](api/project_forge/configurations/composition.md#project_forge.configurations.composition.Composition)
+A [composition](api/project_forge/models/composition.md#project_forge.models.composition.Composition)
 defines a set of overlays and methods of context manipulation.
 
 The composition file is a list of overlay objects. An overlay is a reference to a pattern configuration with the ability

diff --git a/docs/reference/location.md b/docs/reference/location.md
@@ -1,8 +1,8 @@
 # Location
 
-The [location](api/project_forge/core/location.md/) is a hashable reference to a source. A location consists of a `url` and `path` combination.
+The [location](api/project_forge/models/location.md) is a hashable reference to a source. A location consists of a `url` and `path` combination.
 
-All fields that accept a [location](api/project_forge/core/location.md/) object will also accept a string representing a URL _or_ a path. So the following are equivalent:
+All fields that accept a [location](api/project_forge/models/location.md) object will also accept a string representing a URL _or_ a path. So the following are equivalent:
 
 ```toml title="Locations specified by strings"
 overlays = [

diff --git a/docs/reference/pattern.md b/docs/reference/pattern.md
@@ -1,8 +1,8 @@
 # Pattern
 
-[Patterns](api/project_forge/configurations/pattern.md#project_forge.configurations.pattern.Pattern) are meant to be focused and reusable chunks of templated content. Although patterns are renderable as-is, you may combine patterns using a *composition.*
+[Patterns](api/project_forge/models/pattern.md#project_forge.models.pattern.Pattern) are meant to be focused and reusable chunks of templated content. Although patterns are renderable as-is, you may combine patterns using a *composition.*
 
-A [pattern](api/project_forge/configurations/pattern.md#project_forge.configurations.pattern.Pattern) consists of a set of template files and a configuration file.
+A [pattern](api/project_forge/models/pattern.md#project_forge.models.pattern.Pattern) consists of a set of template files and a configuration file.
 
 ## Pattern configuration
 
@@ -15,50 +15,51 @@ You may use YAML, JSON, or TOML formatting to define the configuration.
     ```toml
     template_location = "{{ repo_name }}"
     copy_only = [
-        "overrides/**/*", "overrides/**/.*"
+      "overrides/**/*",
+      "overrides/**/.*",
     ]
-    
+
     [[questions]]
     name = "project_name"
     prompt = "What is the human-friendly name of the project?"
     type = "str"
     default = "My Project"
-    
+
     [[questions]]
     name = "package_name"
     prompt = "What is the name of the Python package?"
     type = "str"
     default = "{{ project_name|lower|replace(' ', '_') }}"
-    
+
     [[questions]]
     name = "repo_name"
     prompt = "What is the name of the project repository?"
     type = "str"
     default = "{{ package_name|replace('_', '-') }}"
-    
+
     [[questions]]
     name = "project_description"
     help = "A sentence or two about what this project does."
     type = "str"
     default = ""
-    
+
     [extra_context.requirements]
     docs = [
-        "black",
-        "markdown-customblocks",
-        "mdx-truly-sane-lists",
-        "mkdocs",
-        "mkdocs-click",
-        "mkdocs-gen-files",
-        "mkdocs-git-authors-plugin",
-        "mkdocs-git-committers-plugin",
-        "mkdocs-git-revision-date-localized-plugin",
-        "mkdocs-include-markdown-plugin",
-        "mkdocs-literate-nav",
-        "mkdocs-material",
-        "mkdocs-section-index",
-        "mkdocstrings[python]",
-        "python-frontmatter"
+      "black",
+      "markdown-customblocks",
+      "mdx-truly-sane-lists",
+      "mkdocs",
+      "mkdocs-click",
+      "mkdocs-gen-files",
+      "mkdocs-git-authors-plugin",
+      "mkdocs-git-committers-plugin",
+      "mkdocs-git-revision-date-localized-plugin",
+      "mkdocs-include-markdown-plugin",
+      "mkdocs-literate-nav",
+      "mkdocs-material",
+      "mkdocs-section-index",
+      "mkdocstrings[python]",
+      "python-frontmatter",
     ]
     ```
 
@@ -126,43 +127,43 @@ You may use YAML, JSON, or TOML formatting to define the configuration.
     ```yaml
     template_location: '{{ repo_name }}'
     copy_only:
-    - overrides/**/*
-    - overrides/**/.*
+      - overrides/**/*
+      - overrides/**/.*
     questions:
-    - default: My Project
-      name: project_name
-      prompt: What is the human-friendly name of the project?
-      type: str
-    - default: '{{ project_name|lower|replace('' '', ''_'') }}'
-      name: package_name
-      prompt: What is the name of the Python package?
-      type: str
-    - default: '{{ package_name|replace(''_'', ''-'') }}'
-      name: repo_name
-      prompt: What is the name of the project repository?
-      type: str
-    - default: ''
-      help: A sentence or two about what this project does.
-      name: project_description
-      type: str
+      - default: My Project
+        name: project_name
+        prompt: What is the human-friendly name of the project?
+        type: str
+      - default: "{{ project_name|lower|replace(' ', '_') }}"
+        name: package_name
+        prompt: What is the name of the Python package?
+        type: str
+      - default: "{{ package_name|replace('_', '-') }}"
+        name: repo_name
+        prompt: What is the name of the project repository?
+        type: str
+      - default: ''
+        help: A sentence or two about what this project does.
+        name: project_description
+        type: str
     extra_context:
       requirements:
         docs:
-        - black
-        - markdown-customblocks
-        - mdx-truly-sane-lists
-        - mkdocs
-        - mkdocs-click
-        - mkdocs-gen-files
-        - mkdocs-git-authors-plugin
-        - mkdocs-git-committers-plugin
-        - mkdocs-git-revision-date-localized-plugin
-        - mkdocs-include-markdown-plugin
-        - mkdocs-literate-nav
-        - mkdocs-material
-        - mkdocs-section-index
-        - mkdocstrings[python]
-        - python-frontmatter
+          - black
+          - markdown-customblocks
+          - mdx-truly-sane-lists
+          - mkdocs
+          - mkdocs-click
+          - mkdocs-gen-files
+          - mkdocs-git-authors-plugin
+          - mkdocs-git-committers-plugin
+          - mkdocs-git-revision-date-localized-plugin
+          - mkdocs-include-markdown-plugin
+          - mkdocs-literate-nav
+          - mkdocs-material
+          - mkdocs-section-index
+          - mkdocstrings[python]
+          - python-frontmatter
     ```
 
 Includes:
@@ -175,23 +176,23 @@ Includes:
 
 - how context is presented
 - can you have templates fill parts of other overlays?
-  - Like treating each overlay as a chain map
+    - Like treating each overlay as a chain map
 - need to figure out how to use inheritance and multiple sources of templates
 - need to figure out all the files (including overwrites and )
 
 ## Pattern source manager
 
 - Contains the interface for accessing local copies of the pattern templates
 - Caching logic
-  - Local checkouts for remote repositories
+    - Local checkouts for remote repositories
 - Hashing sources to detect changes
 
 ### Sources of patterns
 
 - Local directory
-  - For local Git repositories, we will need to deal with the potential of a dirty repo and how that affects the snapshot
-    - Treat it as a Non-Git repository
-    - Don't allow dirty repositories: raise an error
-  - Non-Git directories
-    - Hash the contents of the directory.
-    - Treat it as "always new".
+    - For local Git repositories, we will need to deal with the potential of a dirty repo and how that affects the snapshot
+        - Treat it as a Non-Git repository
+        - Don't allow dirty repositories: raise an error
+    - Non-Git directories
+        - Hash the contents of the directory.
+        - Treat it as "always new".
diff --git a/docs/tutorials/create_a_pattern.md b/docs/tutorials/create_a_pattern.md
@@ -5,38 +5,47 @@ icon:
 date: 2024-08-28
 comments: true
 ---
+
 # Create a Pattern
 
-We are going to convert an existing project into a pattern. This process is going to require _lots_ of search and replace.
+We are going to convert an existing project into a pattern.
+This process is going to require _lots_ of search and replace.
 
 In another tutorial, we will break it into several patterns.
 
 ## Setup
 
 1. Create a new directory named `patterns.`
-2. Download the example project as a `.zip` file from TODO
-
-3. Decompress the file and copy the `todo-manager` project into `patterns/`.
+1. Download the example project as a `.zip` file from TODO
+1. Decompress the file and copy the `todo-manager` project into `patterns/`.
+1. Inside the `patterns/` directory, create a file named `core_pattern.toml`
 
 !!! Note
 
     If you are doing this with an actual project, remove the `.git` directory if it exists.
 
-4. Inside the `patterns/` directory, create a file named `core_pattern.toml`
-
 ## Extracting questions
 
-Questions are asked of the user during the project generation. Each answer is set as the value of a variable used in patterns. We will go through this example project and highlight information that would or could vary between projects. We will create questions to get the data from the user, and then we will replace the existing values in the example project with placeholders.
+Questions are asked of the user during the project generation.
+Each answer is set as the value of a variable used in patterns.
+We will go through this example project and highlight information that would or could vary between projects.
+We will create questions to get the data from the user,
+and then we will replace the existing values in the example project with placeholders.
 
 ### Different names in different places
 
-The outer folder is named `todo-manager`, the code folder is named `todo_manager`, and the title of the `README.md` file is `Todo Manager`. Are these three different variables that require three different questions? Is this one variable with three permutations that only require one question?
+The outer folder is named `todo-manager`,
+the code folder is named `todo_manager`,
+and the title of the `README.md` file is `Todo Manager`.
+Are these three different variables that require three different questions?
+Is this one variable with three permutations that only require one question?
 
 We will treat them as three variables. However, we don't necessarily require three answers.
 
 ### Project name
 
-Let's start with the title of the `README.md` file. We'll call this the `project_name`. We want to use this wherever we need a human-friendly name. Add a question to `core_pattern.toml`
+Let's start with the title of the `README.md` file. We'll call this the `project_name`.
+We want to use this wherever we need a human-friendly name. Add a question to `core_pattern.toml`
 
 ```toml title="patterns/core_pattern.toml"
 [[questions]]
@@ -48,7 +57,10 @@ default = "My Project"
 
 ### Package name
 
-Now, let's deal with the outer folder name and the code folder. Python package names (the package name registered with the Python package index) are [normalized](https://packaging.python.org/en/latest/specifications/name-normalization/) using hyphens. However, hyphens are not allowed in [Python identifiers](https://docs.python.org/3.12/reference/lexical_analysis.html#identifiers).
+Now, let's deal with the outer folder name and the code folder.
+Python package names (the package name registered with the Python package index)
+are [normalized](https://packaging.python.org/en/latest/specifications/name-normalization/) using hyphens.
+However, hyphens are not allowed in [Python identifiers](https://docs.python.org/3.12/reference/lexical_analysis.html#identifiers).
 
 We'll call the name of the code folder the `package_name`. Add this question to `core_pattern.toml`:
 
@@ -62,7 +74,9 @@ type = "str"
 default = "{{ project_name|lower|replace(' ', '_') }}"
 ```
 
-This sets the default answer to a modification of the previous question's answer. It converts the answer to lowercase and replaces all spaces with underscores. This is likely what the user wants, and if so, they can accept the default without having to type anything.
+This sets the default answer to a modification of the previous question's answer.
+It converts the answer to lowercase and replaces all spaces with underscores.
+This is likely what the user wants, and if so, they can accept the default without having to type anything.
 
 ### Repo name