Working on some initial docs

.github/workflows/python-package.yml

@@ -21,6 +21,7 @@ jobs:
           - "3.8"
           - "3.9"
           - "3.10"
+          - "3.11"
         system:
           - ubuntu-latest
           - macos-latest

README.md

@@ -2,7 +2,7 @@
     =====================================
     generator=datazen
     version=3.1.0
-    hash=c7403ee8217c0260dff97f3404f3af77
+    hash=fe3e09e0d89218f917b0f128f402465c
     =====================================
 -->
 
@@ -27,6 +27,7 @@ This package is tested with the following Python minor versions:
 * [`python3.8`](https://docs.python.org/3.8/)
 * [`python3.9`](https://docs.python.org/3.9/)
 * [`python3.10`](https://docs.python.org/3.10/)
+* [`python3.11`](https://docs.python.org/3.11/)
 
 ## Platform Support
 
@@ -38,6 +39,41 @@ This package is tested on the following platforms:
 
 # Introduction
 
+This project aims to simplify management of user configuration files, user (or
+system-wide) package installations, system settings and more on a variety of
+platforms.
+
+Reasons to use it:
+1. Simplify bootstrapping a fresh system to a "developer workstation" in as few
+steps as possible
+   1. This can be a simpler options for teams or individuals who don't have
+   infrastructure to manage system-install images, system-distribution build
+   systems, other kinds of provisioning automation, etc.
+1. Normalize software configurations for a team of developers, but still allow
+personalized overrides when desired (e.g. text-editor or terminal configs)
+   1. This can help make your team or organization's development environment
+   more approachable to new or inexperienced developers (ask yourself this:
+   are the code changes usually even the hard part?)
+1. Relies on a minimal [data repository](md/data_repository.md) that can be
+managed with version control, shared by multiple people, open source to provide
+examples to the community, etc.
+   1. This enables a workflow for adding, removing, updating and re-configuring
+   software used by a project-ecosystem over time
+
+# Getting Started
+
+This package attempts to adhere to the
+[XDG Base Directory Specification](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html).
+It keeps stateful information that needs to persist between command invocations
+in a `rcmpy` sub-directory in the user-state directory controlled
+by `XDG_STATE_HOME` (or the default: `$HOME/.local/state`).
+
+One tracked piece of stateful information is the location of the current
+[data repository](md/data_repository.md). If this is not changed (via the `use`
+command), it checks a `rcmpy/default` sub-directory in the
+user-config directory controlled by `XDG_CONFIG_HOME` (or the default:
+`$HOME/.config`).
+
 # Command-line Options
 
 ```
@@ -64,6 +100,51 @@ commands:
 
 ```
 
+## Sub-command Options
+
+### `apply`
+
+```
+$ ./venv3.8/bin/rcmpy apply -h
+
+usage: rcmpy apply [-h]
+
+optional arguments:
+  -h, --help  show this help message and exit
+
+```
+
+### `use`
+
+```
+$ ./venv3.8/bin/rcmpy use -h
+
+usage: rcmpy use [-h] [-d] [directory]
+
+positional arguments:
+  directory      the directory to use
+
+optional arguments:
+  -h, --help     show this help message and exit
+  -d, --default  sets the directory back to the package default
+
+```
+
+### `variant`
+
+```
+$ ./venv3.8/bin/rcmpy variant -h
+
+usage: rcmpy variant [-h] variant
+
+positional arguments:
+  variant     new variant to use
+
+optional arguments:
+  -h, --help  show this help message and exit
+
+```
+
 # Internal Dependency Graph
 
 A coarse view of the internal structure and scale of

local/configs/python.yaml

@@ -3,7 +3,7 @@ author_info:
   name: Vaughn Kottler
   email: vaughnkottler@gmail.com
   username: vkottler
-versions: ["3.7", "3.8", "3.9", "3.10"]
+versions: ["3.7", "3.8", "3.9", "3.10", "3.11"]
 
 systems:
   - macos-latest

local/includes/sub_commands.yaml

@@ -0,0 +1,15 @@
+# yamllint disable-file
+---
+default_dirs: false
+
+commands:
+{% for command in ["apply", "use", "variant"] %}
+  - name: help-{{command}}
+    command: "./venv{{python_version}}/bin/{{entry}}"
+    force: true
+    arguments:
+      - {{command}}
+      - "-h"
+    dependencies:
+      - commands-install-local
+{% endfor %}

local/templates/README.md.j2

@@ -1,4 +1,39 @@
 {{python_readme_header_md}}
+
+This project aims to simplify management of user configuration files, user (or
+system-wide) package installations, system settings and more on a variety of
+platforms.
+
+Reasons to use it:
+1. Simplify bootstrapping a fresh system to a "developer workstation" in as few
+steps as possible
+   1. This can be a simpler options for teams or individuals who don't have
+   infrastructure to manage system-install images, system-distribution build
+   systems, other kinds of provisioning automation, etc.
+1. Normalize software configurations for a team of developers, but still allow
+personalized overrides when desired (e.g. text-editor or terminal configs)
+   1. This can help make your team or organization's development environment
+   more approachable to new or inexperienced developers (ask yourself this:
+   are the code changes usually even the hard part?)
+1. Relies on a minimal [data repository](md/data_repository.md) that can be
+managed with version control, shared by multiple people, open source to provide
+examples to the community, etc.
+   1. This enables a workflow for adding, removing, updating and re-configuring
+   software used by a project-ecosystem over time
+
+# Getting Started
+
+This package attempts to adhere to the
+[XDG Base Directory Specification](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html).
+It keeps stateful information that needs to persist between command invocations
+in a `{{package["name"]}}` sub-directory in the user-state directory controlled
+by `XDG_STATE_HOME` (or the default: `$HOME/.local/state`).
+
+One tracked piece of stateful information is the location of the current
+[data repository](md/data_repository.md). If this is not changed (via the `use`
+command), it checks a `{{package["name"]}}/default` sub-directory in the
+user-config directory controlled by `XDG_CONFIG_HOME` (or the default:
+`$HOME/.config`).
 {% if "help" in global %}
 
 # Command-line Options
@@ -10,4 +45,17 @@ $ {{" ".join(help["args"])}}
 ```
 {% endif %}
 
+## Sub-command Options
+{% for command in package["commands"] %}
+
+### `{{command["name"]}}`
+{% set help_data = global["help-" + command["name"]] %}
+
+```
+$ {{" ".join(help_data["args"])}}
+
+{{help_data["stdout"]}}
+```
+{% endfor %}
+
 {{python_readme_dep_graph_md}}

local/templates/data_repository.md.j2

@@ -0,0 +1,5 @@
+# Data Repository
+
+([back](../README.md#getting-started))
+
+TODO.

manifest.yaml

@@ -10,6 +10,7 @@ includes:
   - config/includes/python.yaml
   - config/includes/license.yaml
   - config/includes/funding.yaml
+  - local/includes/sub_commands.yaml
 
 templates:
   - local/templates
@@ -29,6 +30,14 @@ renders:
       - renders-python_readme_header.md
       - renders-python_readme_dep_graph.md
       - commands-help
+      - commands-help-apply
+      - commands-help-use
+      - commands-help-variant
+
+  - name: data_repository.md
+    output_dir: "md"
+    dependencies:
+      - compiles-local
 
   - name: app.py
     output_dir: "{{project}}"
@@ -47,5 +56,6 @@ groups:
       - groups-license
       - groups-funding
       - renders-README.md
+      - renders-data_repository.md
       - renders-app.py
       - renders-all.py

md/data_repository.md

@@ -0,0 +1,13 @@
+<!--
+    =====================================
+    generator=datazen
+    version=3.1.0
+    hash=46e9e1c466d851096049561754127690
+    =====================================
+-->
+
+# Data Repository
+
+([back](../README.md#getting-started))
+
+TODO.

pyproject.toml

@@ -19,6 +19,7 @@ classifiers = [
   "Programming Language :: Python :: 3.8",
   "Programming Language :: Python :: 3.9",
   "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
   "Operating System :: Microsoft :: Windows",
   "Operating System :: MacOS",
   "Operating System :: POSIX :: Linux",

setup.py

@@ -1,7 +1,7 @@
 # =====================================
 # generator=datazen
 # version=3.1.0
-# hash=416bc5bcfd6143aac0a78a91308857db
+# hash=dc0d9f835ecbdaf7ba7d62dc617acb8d
 # =====================================
 
 """
@@ -32,6 +32,7 @@
         "3.8",
         "3.9",
         "3.10",
+        "3.11",
     ],
 }
 setup(