Working on readmes

davegaeddert · davegaeddert · commit 4d56944e54ae · 2024-06-20T13:10:38.000-05:00
diff --git a/bolt-auth/README.md b/bolt-auth/README.md
@@ -4,7 +4,7 @@
 
 Create users and authenticate them.
 
-[link](https://github.com/dropseed/bolt/tree/main/bolt-auth/bolt/auth/config.py)
+[link](https://boltframework.dev/docs/bolt-auth/bolt/auth/config.py)
 
 ## Installation
 
diff --git a/bolt/README.md b/bolt/README.md
@@ -6,12 +6,30 @@ Bolt is a web framework for building products with Python.
 
 With the core `bolt` package you can build an app that:
 
-- Matches [URL patterns](https://github.com/dropseed/bolt/tree/main/bolt/bolt/urls/README.md) to Python views
-- Handles HTTP requests and responses
-- Renders HTML templates with Jinja
-- Processes user input via forms
-- Has a CLI interface
-- Serves static assets (CSS, JS, images)
-- Can be modified with middleware
-- Integrates first-party and third-party packages
-- Has a preflight check system
+- Matches [URL patterns](https://boltframework.dev/docs/bolt/bolt/urls) to Python [views](https://boltframework.dev/docs/bolt/bolt/views)
+- Handles [HTTP requests and responses](https://boltframework.dev/docs/bolt/bolt/http)
+- Renders [HTML templates](https://boltframework.dev/docs/bolt/bolt/templates) with Jinja
+- Processes user input via [forms](https://boltframework.dev/docs/bolt/bolt/forms)
+- Has a [CLI interface](https://boltframework.dev/docs/bolt/bolt/cli)
+- Serves static [assets](https://boltframework.dev/docs/bolt/bolt/assets) (CSS, JS, images)
+- Can be modified with [middleware](https://boltframework.dev/docs/bolt/bolt/middleware)
+- Integrates first-party and third-party [packages](https://boltframework.dev/docs/bolt/bolt/packages)
+- Has a [preflight check system](https://boltframework.dev/docs/bolt/bolt/preflight)
+
+With the official Bolt ecosystem packages you can:
+
+- Integrate a full-featured [database ORM](https://boltframework.dev/docs/bolt-db/)
+- Use a built-in [user authentication](https://boltframework.dev/docs/bolt-auth/) system
+- [Lint and format code](https://boltframework.dev/docs/bolt-code/)
+- Run a [database-backed cache](https://boltframework.dev/docs/bolt-cache/)
+- [Send emails](https://boltframework.dev/docs/bolt-mail/)
+- Streamline [local development](https://boltframework.dev/docs/bolt-dev/)
+- Manage [feature flags](https://boltframework.dev/docs/bolt-flags/)
+- Integrate [HTMX](https://boltframework.dev/docs/bolt-htmx/)
+- Style with [Tailwind CSS](https://boltframework.dev/docs/bolt-tailwind/)
+- Add [OAuth login](https://boltframework.dev/docs/bolt-oauth/) and API access
+- Run tests with [pytest](https://boltframework.dev/docs/bolt-test/)
+- Run a [background job worker](https://boltframework.dev/docs/bolt-worker/)
+- Build [staff tooling and admin dashboards](https://boltframework.dev/docs/bolt-staff/)
+
+Learn more at [boltframework.dev](https://boltframework.dev).
diff --git a/bolt/bolt/README.md b/bolt/bolt/README.md
@@ -4,12 +4,30 @@ Bolt is a web framework for building products with Python.
 
 With the core `bolt` package you can build an app that:
 
-- Matches [URL patterns](./urls/README.md) to Python views
-- Handles HTTP requests and responses
-- Renders HTML templates with Jinja
-- Processes user input via forms
-- Has a CLI interface
-- Serves static assets (CSS, JS, images)
-- Can be modified with middleware
-- Integrates first-party and third-party packages
-- Has a preflight check system
+- Matches [URL patterns](./urls) to Python [views](./views)
+- Handles [HTTP requests and responses](./http)
+- Renders [HTML templates](./templates) with Jinja
+- Processes user input via [forms](./forms)
+- Has a [CLI interface](./cli)
+- Serves static [assets](./assets) (CSS, JS, images)
+- Can be modified with [middleware](./middleware)
+- Integrates first-party and third-party [packages](./packages)
+- Has a [preflight check system](./preflight)
+
+With the official Bolt ecosystem packages you can:
+
+- Integrate a full-featured [database ORM](https://boltframework.dev/docs/bolt-db/)
+- Use a built-in [user authentication](https://boltframework.dev/docs/bolt-auth/) system
+- [Lint and format code](https://boltframework.dev/docs/bolt-code/)
+- Run a [database-backed cache](https://boltframework.dev/docs/bolt-cache/)
+- [Send emails](https://boltframework.dev/docs/bolt-mail/)
+- Streamline [local development](https://boltframework.dev/docs/bolt-dev/)
+- Manage [feature flags](https://boltframework.dev/docs/bolt-flags/)
+- Integrate [HTMX](https://boltframework.dev/docs/bolt-htmx/)
+- Style with [Tailwind CSS](https://boltframework.dev/docs/bolt-tailwind/)
+- Add [OAuth login](https://boltframework.dev/docs/bolt-oauth/) and API access
+- Run tests with [pytest](https://boltframework.dev/docs/bolt-test/)
+- Run a [background job worker](https://boltframework.dev/docs/bolt-worker/)
+- Build [staff tooling and admin dashboards](https://boltframework.dev/docs/bolt-staff/)
+
+Learn more at [boltframework.dev](https://boltframework.dev).
diff --git a/bolt/bolt/assets/README.md b/bolt/bolt/assets/README.md
@@ -1,3 +1,56 @@
-# assets
+# Assets
 
-Serve static assets for your app.
+Serve static assets (CSS, JS, images, etc.) for your app.
+
+The default behavior is for Bolt to serve assets directly via a middleware.
+This is based on [whitenoise](http://whitenoise.evans.io/en/stable/).
+
+## Usage
+
+Generally speaking, the simplest way to include assests in your app is to put them either in `app/assets` or `app/<package>/assets`.
+
+Then in your template you can use the `asset()` function to get the URL.
+
+```html
+<link rel="stylesheet" href="{{ asset('css/style.css') }}">
+```
+
+If you ever need to reference an asset directly in Python code, you can use the `get_asset_url()` function.
+
+```python
+from bolt.assets import get_asset_url
+
+print(get_asset_url("css/style.css"))
+```
+
+## Settings
+
+These are the default settings related to assets handling.
+
+```python
+# app/settings.py
+MIDDLEWARE = [
+    "bolt.middleware.security.SecurityMiddleware",
+    "bolt.assets.whitenoise.middleware.WhiteNoiseMiddleware",  # <--
+    "bolt.middleware.common.CommonMiddleware",
+    "bolt.csrf.middleware.CsrfViewMiddleware",
+    "bolt.middleware.clickjacking.XFrameOptionsMiddleware",
+]
+
+ASSETS_BACKEND = "bolt.assets.whitenoise.storage.CompressedManifestStaticFilesStorage"
+
+# List of finder classes that know how to find assets files in
+# various locations.
+ASSETS_FINDERS = [
+    "bolt.assets.finders.FileSystemFinder",
+    "bolt.assets.finders.PackageDirectoriesFinder",
+]
+
+# Absolute path to the directory assets files should be collected to.
+# Example: "/var/www/example.com/assets/"
+ASSETS_ROOT = BOLT_TEMP_PATH / "assets_collected"
+
+# URL that handles the assets files served from ASSETS_ROOT.
+# Example: "http://example.com/assets/", "http://assets.example.com/"
+ASSETS_URL = "/assets/"
+```
diff --git a/bolt/bolt/cli/README.md b/bolt/bolt/cli/README.md
@@ -10,14 +10,114 @@ which has been one of those most popular CLI frameworks in Python for a long tim
 
 ### `bolt shell`
 
+Open a Python shell with the Bolt loaded.
+
+To auto-load models or run other code at shell launch,
+create an `app/shell.py` and it will be imported automatically.
+
+```python
+# app/shell.py
+from organizations.models import Organization
+
+__all__ = [
+    "Organization",
+]
+```
+
 ### `bolt compile`
 
+Compile static assets (used in the deploy/production process).
+
+Automatically runs `bolt tailwind compile` if [bolt-tailwind](https://boltframework.dev/docs/bolt-tailwind/) is installed.
+
+Automatically runs `npm run compile` if you have a `package.json` with `scripts.compile`.
+
 ### `bolt run`
 
+Run a Python script in the context of your app.
+
 ### `bolt legacy`
 
+A temporary holdover for running the old `manage.py` commands that haven't been converted yet.
+
+### `bolt preflight`
+
+Run preflight checks to ensure your app is ready to run.
+
+### `bolt create`
+
+Create a new local package.
+
+### `bolt setting`
+
+View the runtime value of a named setting.
+
 ## Adding commands
 
+### Add an `app/cli.py`
+
+You can add "root" commands to your app by defining a `cli` function in `app/cli.py`.
+
+```python
+import click
+
+
+@click.group()
+def cli():
+    pass
+
+
+@cli.command()
+def custom_command():
+    click.echo("An app command!")
+```
+
+Then you can run the command with `bolt`.
+
+```bash
+$ bolt custom-command
+An app command!
+```
+
 ### Add CLI commands to your local packages
 
+Any package in `INSTALLED_PACKAGES` can define CLI commands by creating a `cli.py` in the root of the package.
+In `cli.py`, create a command or group of commands named `cli`.
+
+```python
+import click
+
+
+@click.group()
+def cli():
+    pass
+
+
+@cli.command()
+def hello():
+    click.echo("Hello, world!")
+```
+
+Bolt will use the name of the package in the CLI,
+then any commands you defined.
+
+```bash
+$ bolt <pkg> hello
+Hello, world!
+```
+
 ### Add CLI commands to published packages
+
+Some packages, like [bolt-dev](https://boltframework.dev/docs/bolt-dev/),
+never show up in `INSTALLED_PACKAGES` but still have CLI commands.
+These are detected via Python entry points.
+
+An example with `pyproject.toml` and Poetry:
+
+```toml
+# pyproject.toml
+[tool.poetry.plugins."bolt.cli"]
+"dev" = "bolt.dev:cli"
+"pre-commit" = "bolt.dev.precommit:cli"
+"contrib" = "bolt.dev.contribute:cli"
+```
diff --git a/bolt/bolt/csrf/README.md b/bolt/bolt/csrf/README.md
@@ -1,3 +1,3 @@
-# csrf
+# CSRF
 
 Cross-Site Request Forgery (CSRF) protection.
diff --git a/bolt/bolt/files/README.md b/bolt/bolt/files/README.md
@@ -0,0 +1,3 @@
+# Files
+
+File upload handling and utilities.
diff --git a/bolt/bolt/http/README.md b/bolt/bolt/http/README.md
@@ -1,7 +1 @@
 # HTTP
-
-Every HTTP request deserves and HTTP response.
-
-At the end of the day,
-Bolt is for building websites and that means receiving HTTP requests
-and returning HTTP responses.
diff --git a/bolt/bolt/logs/README.md b/bolt/bolt/logs/README.md
@@ -4,7 +4,7 @@ Default logging settings and key-value logger.
 
 In Python, logging can be a surprisingly complex topic.
 
-So Bolt includes some easy-to-use defaults that "just work".
+So Bolt aims for easy-to-use defaults that "just work".
 
 ## `app_logger`
 
diff --git a/scripts/compile-readmes b/scripts/compile-readmes
@@ -4,6 +4,8 @@ compile_readme() {
     package_readme="$1"
     code_readme="$2"
 
+    echo "Compiling $code_readme to $package_readme"
+
     header_comment="<!-- This file is compiled from $code_readme. Do not edit this file directly. -->\n"
 
     # Copy bolt/bolt/README.md to bolt/README.md and add a header comment
@@ -13,8 +15,8 @@ compile_readme() {
     code_base_dir=$(dirname "$code_readme")
 
     # Find and replace any "](./" markdown links and replace with a full github.com url
-    github_url="https://github.com/dropseed/bolt/tree/main"
-    sed -i '' -e "s#](\./\([^)]*\))#]($github_url/$code_base_dir/\1)#g" "$package_readme"
+    docs_url="https://boltframework.dev/docs"
+    sed -i '' -e "s#](\./\([^)]*\))#]($docs_url/$code_base_dir/\1)#g" "$package_readme"
 }
 
 compile_readme "bolt/README.md" "bolt/bolt/README.md"
diff --git a/scripts/pre-commit b/scripts/pre-commit
@@ -8,3 +8,7 @@ echo "${BOLD}Checking with ruff${NORMAL}"
 echo ""
 echo "${BOLD}Running tests${NORMAL}"
 ./scripts/test
+
+echo ""
+echo "${BOLD}Compiling readmes${NORMAL}"
+./scripts/compile-readmes

Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,3 @@`
`1`		`-# csrf`
	`1`	`+# CSRF`
`2`	`2`
`3`	`3`	`Cross-Site Request Forgery (CSRF) protection.`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+# Files`
	`2`	`+`
	`3`	`+File upload handling and utilities.`