Website integration

.github/workflows/release.yml

@@ -0,0 +1,32 @@
+name: Release
+
+on:
+  repository_dispatch:
+    types: [docs]
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: webfactory/[email protected]
+        with:
+          ssh-private-key: ${{ secrets.SSH_KEY }}
+      - uses: actions/checkout@v4
+      - name: Install Crystal
+        uses: crystal-lang/install-crystal@v1
+      - name: Install Components
+        run: shards install
+      - uses: actions/setup-python@v5
+        with:
+          python-version: 3.x
+      - run: pip install -r requirements.txt
+      - name: Build Docs
+        run: make build
+      - name: Publish to Cloudflare Pages
+        uses: cloudflare/pages-action@v1
+        with:
+          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+          projectName: athenaframework
+          directory: site
+          branch: master

.github/workflows/sync.yml

@@ -18,3 +18,30 @@ jobs:
         env:
           BEFORE_SHA: ${{ github.event.before }}
           AFTER_SHA: ${{ github.event.after }}
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: webfactory/[email protected]
+        with:
+          ssh-private-key: ${{ secrets.SSH_KEY }}
+      - uses: actions/checkout@v4
+      - name: Install Crystal
+        uses: crystal-lang/install-crystal@v1
+      - name: Install Components
+        run: shards install
+        env:
+          SHARDS_OVERRIDE: shard.dev.yml
+      - uses: actions/setup-python@v5
+        with:
+          python-version: 3.x
+      - run: pip install -r requirements.txt
+      - name: Build Docs
+        run: make build
+      - name: Publish to Cloudflare Pages
+        uses: cloudflare/pages-action@v1
+        with:
+          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+          projectName: athenaframework
+          directory: site
+          branch: dev

.gitignore

@@ -2,10 +2,14 @@
 *.dwarf
 /.shards/
 /bin/
-/docs/
 /lib/
 /logs/
 
 # Libraries don't need dependency lock
 # Dependencies will be locked in application that uses them
 /shard.lock
+
+__pycache__
+.cache
+.venv
+site/

.typos.toml

@@ -6,6 +6,7 @@ recruses = "recurses"
 dimenstional = "dimensional"
 extreanous = "extraneous"
 instantaintg = "instantiating"
+alternateively = "alternatively"
 
 [files]
 extend-exclude = [

CONTRIBUTING.md

@@ -32,7 +32,7 @@ From here, the tests for a specific component may be ran via the helper script:
 $ ./scripts/test.sh routing
 ```
 
-Or alternateively, for all components:
+Or alternatively, for all components:
 
 ```sh
 $ ./scripts/test.sh

Makefile

@@ -0,0 +1,41 @@
+-include Makefile.local # for optional local config
+
+OUTPUT_DIR ?= ./site ## Build directory (default: ./site)
+
+MKDOCS ?= ./.venv/bin/mkdocs
+PIP ?= ./.venv/bin/pip3
+PIP_COMPILE ?= ./.venv/bin/pip-compile
+
+.PHONY: build
+build: ## Build website into build directory
+build: $(OUTPUT_DIR)
+
+$(OUTPUT_DIR): $(MKDOCS)
+	$(MKDOCS) build -d $(OUTPUT_DIR)
+
+.PHONY: serve
+serve: ## Run live-preview server
+serve: $(MKDOCS)
+	$(MKDOCS) serve
+
+deps: $(MKDOCS)
+
+$(MKDOCS): $(PIP) requirements.txt
+	$(PIP) install -q -r requirements.txt
+
+$(PIP):
+	python3 -m venv .venv
+	./.venv/bin/pip3 install -q pip-tools
+
+.PHONY: upgrade
+upgrade: ## Upgrade mkdocs deps
+	$(PIP_COMPILE) -U requirements.in
+
+.PHONY: clean
+clean: ## Remove build directories
+	rm -rf $(OUTPUT_DIR)
+	find src/components -type d -name "site" -exec rm -rf {} +
+
+.PHONY: clean_deps
+clean_deps: ## Remove .venv directory
+	rm -rf .venv

docs/README.md

@@ -0,0 +1,45 @@
+## Athena
+
+Athena is a collection of general-purpose, robust, independent, and reusable components with the goal of powering a software ecosystem.
+These include:
+
+* [Clock](/Clock) (`ACLK`) - Decouples applications from the system clock
+* [Config](/Config) (`ACF`) - Common library for configuring Athena components
+* [Console](/Console) (`ACON`) - Allows the creation of CLI based commands
+* [DependencyInjection](/DependencyInjection) (`ADI`) - Robust dependency injection service container framework
+* [Dotenv](/Dotenv) - Registers environment variables from a `.env` file
+* [EventDispatcher](/EventDispatcher) (`AED`) - A Mediator and Observer pattern event library
+* [ImageSize](/ImageSize) (`AIS`) - Measures the size of various image formats
+* [Mercure](/Mercure) (`AMC`) - Allows easily pushing updates to web browsers and other HTTP clients using the Mercure protocol
+* [Negotiation](/Negotiation) (`ANG`) - Framework agnostic content negotiation library
+* [Routing](/Routing) (`ART`) - A performant and robust HTTP based routing library/framework
+* [Serializer](/Serializer) (`ASR`) - Object (de)serialization library
+* [Spec](/Spec) (`ASPEC`) - Common/helpful [Spec](https://crystal-lang.org/api/Spec.html) compliant testing utilities
+* [Validator](/Validator) (`AVD`) - Object/value validation library
+
+These components may be used on their own to aid in existing projects or integrated into existing (or new) frameworks.
+
+TIP: Each component may also define additional shortcut aliases. Check the `Aliases` page of each component in the [API Reference](./api_reference.md) for more information.
+
+## Athena Framework
+
+Athena also provides the [Framework](./getting_started/README.md) component that integrates select components into a single cohesive, flexible, and modular framework.
+It is designed in such a way to be non-intrusive and not require a strict organizational convention in regards to how a project is setup;
+this allows it to use a minimal amount of setup boilerplate while not preventing it for more complex projects.
+Not every component needs to be used or understood to start using the framework, only those which are required for the task at hand.
+
+### Feature Highlights
+
+Athena Framework has quite a few unique features that set it a part from other Crystal frameworks:
+
+* Follows the SOLID principles to encourage good software design
+* Architected in such a way to allow maximum flexibility without needing to fight against the framework
+* Uses annotations as a means of extension/customization
+* Built-in testing utilities
+
+TIP: The [demo](https://github.com/athena-framework/demo) application serves as a good example of what an application using the framework could look like.
+
+## Resources
+
+* [Discord Server](https://discord.gg/TmDVPb3dmr)
+* [GitHub Repository](https://github.com/athena-framework/athena)

docs/api_reference.md

@@ -0,0 +1,2 @@
+Links to the API docs of each component may be found in this section.
+These can be a good reference for more in-dept, component specific information, or how when using the component outside of the framework.

docs/css/index.css

@@ -0,0 +1,58 @@
+/* https://mkdocstrings.github.io/crystal/styling.html#recommended-styles */
+
+/* Indentation of sub-items */
+div.doc-contents:not(.first) {
+  padding-left: 15px;
+  border-left: 4px solid rgba(230, 230, 230);
+}
+
+/* Additional Customizations */
+
+body {
+    font-size: 1rem;
+}
+
+/* Increased spacing between macro & instance methods. */
+.doc-macro + .doc-macro,
+.doc-instance_method + .doc-instance_method {
+  margin-top: 3em;
+}
+
+.md-typeset pre>code::-webkit-scrollbar {
+  height: 0.4em;
+}
+/* Slightly more compact headings */
+h1.doc-heading {
+  font-size: 1.3rem;
+}
+h3.doc-heading {
+  font-size: 0.85rem;
+  background: var(--md-code-bg-color);
+  border-radius: 2px;
+}
+
+h3.schema-heading {
+  margin: 0;
+}
+
+.schema-default, .schema-type {
+  display: inline;
+}
+
+.schema-type p {
+  display: inline;
+}
+
+.schema-default p {
+  display: inline;
+}
+
+/* Make content grid a bit wider (but never wider than the screen) */
+.md-grid {
+  max-width: min(80rem, 100vw);
+}
+
+/* Make sure page content doesn't get too wide on big 4k monitors */
+.md-content {
+    max-width: 85ch;
+}

docs/getting_started/README.md

@@ -0,0 +1,20 @@
+Athena Framework does not have any other dependencies outside of Crystal and Shards.
+It is designed in such a way to be non-intrusive and not require a strict organizational convention in regards to how a project is setup;
+this allows it to use a minimal amount of setup boilerplate while not preventing it for more complex projects.
+
+## Install Athena Framework
+
+Add the framework component to your `shard.yml`:
+
+```yaml
+dependencies:
+  athena:
+    github: athena-framework/framework
+    version: ~> 0.18.0
+```
+
+Then run `shards install`.
+This will install the framework component and its required component dependencies.
+Finally require it via `require "athena"`, then are all set to starting using the framework, starting with [Routing & HTTP](./routing.md).
+
+TIP: Check out the [skeleton](https://github.com/athena-framework/skeleton) template repository to get up and running quickly.

docs/getting_started/commands.md

@@ -0,0 +1,60 @@
+The Athena Framework comes with a built-in integration with the [Athena::Console](/Console) component.
+This integration can be a way to define alternate entry points into your business logic,
+such as for use with scheduled jobs (Cron, Airflow, etc), or one-off internal/administrative things (running migrations, creating users, etc)
+all the while sharing the same dependencies due to it also leveraging [dependency injection](../why_athena.md#dependency-injection).
+
+## Basic Usage
+
+Similar to [event listeners](./middleware.md#event-listeners), console commands can simply be registered as a service to be automatically registered.
+If using the preferred [ACONA::AsCommand](/Console/Annotations/AsCommand) annotation, they are registered in a lazy fashion, meaning only the command(s) you execute will actually be instantiated.
+
+```crystal
+@[ADI::Register]
+@[ACONA::AsCommand("admin:create-user", description: "Creates a new internal user")]
+class AdminCreateUser < ACON::Command
+  # A constructor can be defined to leverage existing services if applicable
+  #def initialize(
+  #  @some_serive : MyService
+  #)
+  #  # Just be sure to call `super()`!
+  #  super()
+  #end
+
+  # Configure the command by adding arguments, options, aliases, etc.
+  protected def configure : Nil
+    self
+      .argument("id", :required, "The employee's ID")
+      .argument("name", :required, "The user's name")
+      .argument("email", :optional, "The user's email. Assumed to be first.last if not provided")
+      .option("admin", nil, :none, "If the user should be created as an internal admin")
+  end
+
+  protected def execute(input : ACON::Input::Interface, output : ACON::Output::Interface) : ACON::Command::Status
+    # Provides a standardized format for how to display text in the terminal
+    style = ACON::Style::Athena.new input, output
+
+    input.argument "id", Int32   # => 12
+    name = input.argument "name" # => "George Dietrich"
+    input.argument "email"       # => nil
+    input.option "admin", Bool   # => true
+
+    # Implement your business logic
+
+    style.success "Successfully created a user for #{name}!"
+
+    # Note the command executed successfully
+    Status::SUCCESS
+  end
+end
+```
+
+From here, if the application was created using the [skeleton](https://github.com/athena-framework/skeleton), commands can be executed via `shards run console -- admin:create-user 12 "George Dietrich" --admin`.
+Otherwise see [Athena::Console](/Console) for how to setup your CLI entry point.
+
+NOTE: During *development* the console binary needs to re-build the application in order to have access to the changes made since last execution.
+When deploying a *production* console binary, or if not doing any new console command dev, build it with the `--release` flag for increased performance.
+
+## Built-in Commands
+
+The framework also comes with some helpful built-in commands to either help with debugging, or provide framework specific features.
+See each command within the [ATH::Commands](/Framework/Commands) namespace for more information.