Refactor CLI commands and add documentation

CHANGELOG.rst

@@ -5,6 +5,7 @@ DEV
 ---
 
 * Switch from Copier to Typer and add comprehensive tests for project generation
+* Switch docs to Material for MkDocs and host on https://docs.proteanhq.com
 
 0.11.0
 ------

docs/guides/cli/discovery.md

@@ -0,0 +1,40 @@
+# Domain Discovery
+
+In most cases, you will use the `protean` script to interact with your domain 
+over the CLI. The script must be told where to find your domain to load and 
+initialize it, prepping it for your use. The `--domain` option is used to 
+specify how to load the domain.
+
+While `--domain` supports a variety of options for specifying your domain, 
+the below typical values cover most use cases:
+
+**(nothing)**
+
+A "domain" or "subdomain" is imported (as a ".py" file, or package),
+automatically detecting a domain (``domain`` or ``subdomain``).
+
+**`--domain auth`**
+
+The given name is imported, automatically detecting a domain (``domain`` or
+``subdomain``).
+
+!!! note
+
+    ``--domain`` has three parts: an optional path that sets the current working
+    directory, a Python file or dotted import path, and an optional variable
+    name of the instance. The following values demonstrate these
+    parts:
+
+    - ``--app src/auth``
+        Sets the current working directory to ``src`` then imports ``hello``.
+
+    - ``--app auth.domain``
+        Imports the path ``auth.domain``.
+
+    - ``--app auth:sso``
+        Uses the ``sso`` Protean instance in ``auth``.
+
+    If ``--domain`` is not set, the command will try to import "domain" or
+    "subdomain" (as a ".py" file, or package) and try to detect an Protean
+    instance. Within the given import, the command looks for an domain instance
+    named ``domain`` or ``subdomain``, then any domain instance.

docs/guides/cli/docs.md

@@ -0,0 +1,35 @@
+# `protean docs`
+
+The `protean docs preview` command starts a live preview server for Protean
+documentation. This allows you to view changes in real-time as you edit.
+
+## Usage
+
+```shell
+protean docs preview [OPTIONS]
+```
+
+## Options
+
+- `--help`: Shows the help message and exits.
+
+## Running a Preview Server
+
+To start the live preview server for your project's documentation, simply run
+the command without any additional options:
+
+```shell
+protean docs preview`
+```
+
+This will start a local server, usually accessible via a web browser at a URL
+such as `http://localhost:8000`. The exact URL will be displayed in your
+command line interface once the server is running:
+
+```shell
+INFO    -  Building documentation...
+INFO    -  Cleaning site directory
+INFO    -  Documentation built in 0.56 seconds
+INFO    -  [09:45:08] Watching paths for changes: 'docs', 'mkdocs.yml'
+INFO    -  [09:45:08] Serving on http://127.0.0.1:8000/
+```

docs/guides/cli/index.md

@@ -0,0 +1,22 @@
+# Command Line Interface
+
+When you install Protean, you also get a handy command line interface - the `protean` script - in your virtualenv. Driven by [Typer](https://typer.tiangolo.com), the script gives access to commands that can help you scaffold projects, generate new code, and run background servers. The `--help` option will give more information about any commands and options.
+
+Most commands accept a domain instance to load and initialize, prepping it for
+shell access. The [`--domain`](discovery.md) option is used to specify how to
+load the domain.
+
+| Command                        |                                    |
+| :----------------------------- | :----------------------------------|
+| [`protean new`](new.md)        | Creating a domain                  |
+| [`protean shell`](shell.md)    | Working with the shell             |
+
+!!! note
+
+    **Developing Protean:** There are a few additional commands to help you if you
+    want to contribute to Protean.
+
+    | Command                        |                                    |
+    | :----------------------------- | :----------------------------------|
+    | [`protean docs`](docs.md)      | Documentation helpers              |
+    | [`protean test`](test.md)      | Testing helpers                    |

docs/guides/cli/new.md

@@ -0,0 +1,62 @@
+
+# `protean new`
+
+The `protean new` command initializes a new project with a given name. 
+
+## Usage
+
+```shell
+protean new [OPTIONS] PROJECT_NAME
+```
+
+## Arguments
+
+| Argument       | Description             | Default | Required |
+|----------------|-------------------------|---------|----------|
+| `PROJECT_NAME` | Name of the new project | None    | Yes      |
+
+## Options
+
+- `--output-dir`, `-o`: Specifies the directory where the project should be 
+created. If not provided, the current directory is used.
+
+!!! note
+    Throws an error if the output directory is not found or not empty.
+    Combine with `--force` to overwrite existing directory.
+
+- `--data`, `-d`: Accepts one or more key-value pairs to be included in
+the project's configuration.
+- `--help`: Shows the help message and exits.
+
+### Behavior Modifiers
+
+- `--pretend`, `-p`: Runs the command in a "dry run" mode, showing what
+would be done without making any changes.
+- `--force`, `-f`: Forces the command to run even if it would overwrite
+existing files.
+
+## Examples
+
+### Creating a New Project
+
+To create a new project named "authentication" in the current directory:
+
+```shell
+protean new authentication
+```
+
+### Specifying an Output Directory
+
+To create a new project in a specific directory:
+
+```shell
+protean new authentication -o /path/to/directory
+```
+
+### Using Configuration Data
+
+To pass key-value pairs for project configuration:
+
+```shell
+protean new authentication -d key1 value1 -d key2 value2
+```

docs/guides/cli/shell.md

@@ -0,0 +1,40 @@
+# `protean shell`
+
+The `shell` command starts an interactive shell with your Protean application 
+pre-loaded. On the underside, the console command uses `ipython`, so if you've 
+ever used it, you'll be right at home. This is useful for testing out quick 
+ideas with code and changing data server-side without using an interface.
+
+## Usage
+
+```shell
+protean shell [OPTIONS]
+```
+
+## Options
+
+| Option      | Description                               | Default |
+|-------------|-------------------------------------------|---------|
+| `--domain`  | Sets the domain context for the shell.    | `.`     |
+| `--help`    | Shows the help message and exits.         |         |
+
+## Launching the Shell
+
+To launch the interactive shell with default settings:
+
+```shell
+protean shell
+```
+
+### Specifying a Domain
+
+To launch the shell within a specific domain context, use the `--domain` option 
+followed by the domain name:
+
+```shell
+protean shell --domain auth
+```
+
+This command will initiate the shell in the context of `auth` domain, allowing
+you to perform domain-specific operations more conveniently. Read [Domain 
+Discovery](discovery.md) for options to specify the domain.

docs/guides/cli/test.md

@@ -0,0 +1,45 @@
+# `protean test`
+
+The `protean test` command is used to run unit tests. You can specify the
+category of tests to run using the `--category` option.
+
+## Usage
+
+```shell
+protean test [OPTIONS]
+```
+
+## Options
+
+| Option              | Description                               | Default |
+|---------------------|-------------------------------------------|---------|
+| `--category`, `-c`  | Specifies the category of tests to run.  |         |
+| `--help`            | Shows the help message and exits.         |         |
+
+
+Category Options:
+
+- `CORE`: Runs core framework tests. This is the default category if none is specified.
+- `EVENTSTORE`: Runs tests related to the event store functionalities.
+- `DATABASE`: Runs database-related tests.
+- `FULL`: Runs all available tests, including core, event store, and database tests.
+
+## Examples
+
+### Run core framework tests (the default)
+
+```shell
+protean test
+```
+
+### Run database related tests
+
+```shell
+protean test --category DATABASE
+```
+
+### Run all tests with coverage
+
+```shell
+protean test --category FULL
+```

docs/guides/index.md

@@ -0,0 +1,3 @@
+# User Guide
+
+[Command Line Interface](cli/index.md)

docs/index.md

@@ -19,10 +19,10 @@ Protean is a DDD and CQRS-based framework that helps you build Event-driven appl
 
 Protean helps you build applications that can scale and adapt to growing requirements without significant rework.
 
-At its core, Protean encourages a Domain-Driven Design (DDD) approach to development, with support for artifacts necessary to express your domain succinctly and precisely. It also allows you to remain agnostic to the underlying technology by keeping implementation details out of view.
+At its core, Protean encourages a Domain-Driven Design (DDD) approach to development, with out-of-the-box support for tactical patterns necessary to express your domain succinctly and precisely. It also allows you to remain agnostic to the underlying technology by keeping implementation details out of view.
 
 Protean can be thought of having three capabilities:
 
 - *Service-Oriented* - Develop your application as one or more subdomains that run independently as Microservices
 - *Event-Driven*: - Use events to propagate changes across subdomains or become eventually consistent within a Bounded Context.
-- *Adapter-based*: - Use Remain technology-agnostic by exposing Port interfaces to the infrastructure, with multiple adapters supported out of the box.
+- *Adapter-Based*: - Use Remain technology-agnostic by exposing Port interfaces to the infrastructure, with multiple adapters supported out of the box.

mkdocs.yml

@@ -22,14 +22,34 @@ theme:
     - navigation.tracking
     - navigation.tabs
     - navigation.tabs.sticky
-    - navigation.sections
+    - navigation.expand
     - navigation.path
     - navigation.prune
     - navigation.indexes
     - toc.follow
     - navigation.top
+    - search.suggest
+    - search.highlight
+    - content.tabs.link
+    - content.tooltips
+    - content.code.annotate
+    - content.code.copy
+    - content.code.select
+markdown_extensions:
+  - admonition
+  - pymdownx.details
+  - pymdownx.superfences
 nav:
   - Protean: index.md
+  - Guides:
+    - guides/index.md
+    - Command Line Interface:
+      - guides/cli/index.md
+      - guides/cli/discovery.md
+      - guides/cli/new.md
+      - guides/cli/shell.md
+      - guides/cli/docs.md
+      - guides/cli/test.md
   - Community: 
-      - community/index.md
-      - community/contributing.md
+    - community/index.md
+    - community/contributing.md