From 7d48f18b709ff445d614830203b3db7f85b1c40c Mon Sep 17 00:00:00 2001 From: Corey Oordt Date: Tue, 24 Dec 2024 13:50:17 -0600 Subject: [PATCH] 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. --- README.md | 4 + docs/cli.md | 8 ++ docs/reference/composition.md | 2 +- docs/reference/location.md | 4 +- docs/reference/pattern.md | 129 +++++++++++++++-------------- docs/tutorials/create_a_pattern.md | 36 +++++--- 6 files changed, 105 insertions(+), 78 deletions(-) create mode 100644 docs/cli.md diff --git a/README.md b/README.md index ffbcf78..1bd1607 100644 --- 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) + + 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." + + diff --git a/docs/cli.md b/docs/cli.md new file mode 100644 index 0000000..4821b38 --- /dev/null +++ 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 index f3def2b..42fc0af 100644 --- 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 index 6d17fe0..38371fb 100644 --- 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 index 0a297d7..8a02b25 100644 --- 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,7 +176,7 @@ 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 ) @@ -183,15 +184,15 @@ Includes: - 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 index 30b5ba1..81bb109 100644 --- 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