Merge pull request #79 from darrenburns/august-improvements

Various changes

docs/CHANGELOG.md

@@ -0,0 +1,40 @@
+## 1.11.0 [August 2024]
+
+### Added
+
+- This file, `CHANGELOG.md`.
+- Launch docs website.
+- Duplicate request (with new request popup) under cursor in tree with ++d++.
+- "Quick" duplicate request (without new request popup, request name is auto-generated) under cursor in tree with ++shift+d++.
+- Delete request (with confirmation modal) under cursor in tree with ++backspace++.
+- "Quick" delete request (without confirmation modal) under cursor in tree with ++shift+backspace++.
+- "Quit Posting" added to command palette.
+- Move the sidebar to the right or left using `collection_browser.position: 'right' | 'left'` config.
+- Refinements to "galaxy" theme.
+- "galaxy" theme is now default.
+- Help text added to "empty state" in the collection browser.
+- Extend info in the "Collection Browser" help modal.
+- Visual indicator (a red bar on the left) on Input fields that contain invalid values.
+- Toast message now appears when trying to submit the 'new request' modal with invalid values.
+- Public roadmap (initial brain-dump version).
+
+### Fixed
+- Ensure the location of the request on disk in the `Info` tab wraps instead of clipping out of view.
+- Inserting requests in sorted position on creation.
+- Prevent creating requests with no name.
+- Prevent writing paths in the file-name field in the new request modal.
+- Prevent specifying paths outside of the open collection dir in the directory field in the new request modal.
+- Fix variables not being substituted into several fields, including auth.
+
+### Changed
+
+- Upgrade to Textual version 0.76.0
+- Change logic to render bindings in help modal to reflect new Textual API.
+- Sort order of requests in the tree improved.
+
+
+---
+
+!!! note
+    Changes prior to 1.11.0 are not documented here.
+    Please see the [Releases page](https://github.com/darrenburns/posting/releases) on GitHub for information on changes prior to 1.11.0.

docs/guide/collections.md

@@ -0,0 +1,42 @@
+## Overview
+
+A *collection* is just a directory on your file system which may or may not contain requests in the `.posting.yaml` format.
+
+There's absolutely nothing special about a collection.
+It contains no "special files" or metadata -- it's just a directory.
+It could even be empty.
+"Collection" is simply the name we give to the directory which we've loaded into Posting.
+
+## The default collection
+
+If you launch Posting without any arguments, it will load the *default collection*, which is stored in Posting's reserved data directory on your file system.
+You can check where this is by running `posting locate collection`.
+
+This is useful to get started quickly, but you'll probably want to create your own collection directory and load it instead.
+This makes it easier to organize your requests and check them into version control.
+
+## Creating a collection
+
+A collection is just a directory, so you can create a collection by simply creating an empty directory anywhere on your file system.
+
+## Loading a collection
+
+If you want to load a collection, you can do so by passing the path to the collection directory to Posting:
+
+```bash
+posting --collection path/to/collection
+```
+
+## Example
+
+
+
+To open a collection (a directory containing requests), use the `--collection` option:
+
+```bash
+posting --collection path/to/collection
+```
+
+This will recursively find and display requests in the sidebar.
+If you don't supply a directory, Posting will use the default collection directory.
+You can check where this is by running `posting locate collection`.

docs/guide/command_palette.md

@@ -0,0 +1,12 @@
+## Overview
+
+The *command palette* is a way to search for and execute commands in Posting.
+
+Some functionality in Posting can only be accessed through the command palette.
+
+It can be used to switch themes, show/hide parts of the UI, and more.
+
+### Using the command palette
+
+Press ++ctrl+p++ to open the command palette.
+

docs/guide/configuration.md

@@ -0,0 +1,132 @@
+## Overview
+
+Posting can be configured using a configuration file, environment variables, and/or `.env` files.
+
+Configuration values are loaded in the following order of precedence (highest to lowest):
+
+1. Configuration file
+2. Environment variables
+3. `.env` files
+
+## Configuration file
+
+You can write configuration for Posting using YAML.
+
+The location of the config file can be checked using the command `posting locate config`.
+
+Here's an example configuration file:
+
+```yaml
+theme: galaxy
+layout: horizontal
+response:
+  prettify_json: false
+heading:
+  visible: true
+  show_host: false
+```
+
+## Environment variables
+
+All configuration values can also be set as environment variables.
+
+Simply prefix the name of the config with `POSTING_` and set it as an environment variable.
+
+For nested configuration values, use `__` as the delimiter. So to set `heading.visible` to `false`, you can set the environment variable `POSTING_HEADING__VISIBLE=false`.
+
+For example, to set the theme to `galaxy`, you can set the environment variable `POSTING_THEME=galaxy`.
+
+### dotenv (`.env`) files
+
+Posting also supports `.env` (dotenv) files, which are useful if you want to swap out environment variable values depending on the environment you're working in (for example, "dev" vs "prod").
+
+You can tell Posting to use a `.env` file using the `--env` option.
+This option can be supplied multiple times to load multiple `.env` files.
+
+Here's an example `.env` file:
+
+```bash
+POSTING_THEME="cobalt"
+POSTING_LAYOUT="vertical"
+POSTING_HEADING__VISIBLE="false"
+```
+
+Dotenv files are separate from collections, although you may wish to include them inside a collection to make it easy to version and share with others.
+
+## Configuring SSL
+
+Posting verifies SSL certificates by default using the CA bundle provided by the `certifi` package.
+
+### SSL certificate configuration
+
+Posting can load custom CA bundles from a `.pem` file.
+
+The easiest way to do this is in your `config.yaml` file:
+
+```yaml
+ssl:
+  ca_bundle: 'absolute/path/to/certificate.pem'
+```
+
+### Environment-specific certificates
+
+If the required CA bundle differs per environment, you can again use the principle that all configuration can be set as environment variables which can optionally be set and loaded using `--env` and `.env` files:
+
+```bash
+# dev.env
+POSTING_SSL__CA_BUNDLE='/path/to/certificate.pem'
+```
+
+Now load the `dev.env` file when working in the `dev` environment to ensure the dev environment CA bundle is used:
+
+```bash
+posting --env dev.env
+```
+
+### Disabling SSL verification
+
+SSL verification can be disabled on a per-request basis in the "Options" tab.
+
+### Client-side certificates
+
+You can specify local certificates to use as a client-side certificate:
+
+```yaml
+ssl:
+  certificate_path: /path/to/certificate.pem
+  key_file: /path/to/key.key  # optional
+  password: '***********'  # optional password for key_file
+```
+
+## Full configuration reference
+
+The table below lists all available configuration options and their environment variable equivalents, their default values, and descriptions.
+
+| Config Key (Env Var) | Values (Default) | Description |
+|----------------------|------------------|-------------|
+| `theme` (`POSTING_THEME`) | `"posting"`, `"galaxy"`, `"monokai"`, `"solarized-light"`, `"nautilus"`, `"nebula"`, `"alpine"`, `"cobalt"`, `"twilight"`, `"hacker"` (Default: `"posting"`) | Sets the theme of the application. |
+| `load_user_themes` (`POSTING_LOAD_USER_THEMES`) | `true`, `false` (Default: `true`) | If enabled, load user themes from the theme directory, allowing them to be specified in config and selected via the command palette. |
+| `load_builtin_themes` (`POSTING_LOAD_BUILTIN_THEMES`) | `true`, `false` (Default: `true`) | If enabled, load builtin themes, allowing them to be specified in config and selected via the command palette. |
+| `theme_directory` (`POSTING_THEME_DIRECTORY`) | (Default: `${XDG_DATA_HOME}/posting/themes`) | The directory containing user themes. |
+| `layout` (`POSTING_LAYOUT`) | `"vertical"`, `"horizontal"` (Default: `"horizontal"`) | Sets the layout of the application. |
+| `use_host_environment` (`POSTING_USE_HOST_ENVIRONMENT`) | `true`, `false` (Default: `false`) | Allow/deny using environment variables from the host machine in requests via `$env:` syntax. When disabled, only variables defined explicitly in `.env` files will be available for use. |
+| `animation` (`POSTING_ANIMATION`) | `"none"`, `"basic"`, `"full"` (Default: `"none"`) | Controls the animation level. |
+| `response.prettify_json` (`POSTING_RESPONSE__PRETTIFY_JSON`) | `true`, `false` (Default: `true`) | If enabled, JSON responses will be pretty-formatted. |
+| `response.show_size_and_time` (`POSTING_RESPONSE__SHOW_SIZE_AND_TIME`) | `true`, `false` (Default: `true`) | If enabled, the size and time taken for the response will be displayed in the response area border subtitle. |
+| `heading.visible` (`POSTING_HEADING__VISIBLE`) | `true`, `false` (Default: `true`) | Show/hide the app header. |
+| `heading.show_host` (`POSTING_HEADING__SHOW_HOST`) | `true`, `false` (Default: `true`) | Show/hide the hostname in the app header. |
+| `heading.show_version` (`POSTING_HEADING__SHOW_VERSION`) | `true`, `false` (Default: `true`) | Show/hide the version in the app header. |
+| `url_bar.show_value_preview` (`POSTING_URL_BAR__SHOW_VALUE_PREVIEW`) | `true`, `false` (Default: `true`) | Show/hide the variable value preview below the URL bar. |
+| `collection_browser.position` (`POSTING_COLLECTION_BROWSER__POSITION`) | `"left"`, `"right"` (Default: `"left"`) | The position of the collection browser on screen. |
+| `pager` (`POSTING_PAGER`) | (Default: `$PAGER`) | Command to use for paging text. |
+| `pager_json` (`POSTING_PAGER_JSON`) | (Default: `$PAGER`) | Command to use for paging JSON. |
+| `editor` (`POSTING_EDITOR`) | (Default: `$EDITOR`) | Command to use for opening files in an external editor. |
+| `ssl.ca_bundle` (`POSTING_SSL__CA_BUNDLE`) | Absolute path (Default: `unset`) | Absolute path to a CA bundle file/dir. If not set, the [Certifi](https://pypi.org/project/certifi/) CA bundle will be used. |
+| `ssl.certificate_path` (`POSTING_SSL__CERTIFICATE_PATH`) | Absolute path (Default: `unset`) | Absolute path to a client SSL certificate file or directory. |
+| `ssl.key_file` (`POSTING_SSL__KEY_FILE`) | Absolute path (Default: `unset`) | Absolute path to a client SSL key file. |
+| `ssl.password` (`POSTING_SSL__PASSWORD`) | Password for the key file. (Default: `unset`) | Password to decrypt the key file if it's encrypted. |
+| `focus.on_startup` (`POSTING_FOCUS__ON_STARTUP`) | `"url"`, `"method", "collection"` (Default: `"url"`) | Automatically focus the URL bar, method, or collection browser when the app starts. |
+| `focus.on_response` (`POSTING_FOCUS__ON_RESPONSE`) | `"body"`, `"tabs"` (Default: `unset`)| Automatically focus the response tabs or response body text area when a response is received. |
+| `text_input.blinking_cursor` (`POSTING_TEXT_INPUT__BLINKING_CURSOR`) | `true`, `false` (Default: `true`) | If enabled, the cursor will blink in input widgets and text area widgets. |
+| `command_palette.theme_preview` (`POSTING_COMMAND_PALETTE__THEME_PREVIEW`) | `true`, `false` (Default: `false`) | If enabled, the command palette will display a preview of the selected theme when the cursor is over it. This will slow down cursor movement and so is disabled by default. |
+| `use_xresources` (`POSTING_USE_XRESOURCES`) | `true`, `false` (Default: `false`) | Try to create themes called `xresources-dark` and `xresources-light` (see the section below) |

docs/guide/environments.md

@@ -0,0 +1,84 @@
+## Overview
+
+You can use *variables* in input fields and text areas using the `${VARIABLE_NAME}` or `$VARIABLE_NAME` syntax.
+These variables will be substituted into outgoing requests.
+
+<p align="center">
+  <img src="https://github.com/darrenburns/posting/assets/5740731/24b64f58-747b-409e-9672-e354eb8994d8" alt="url-bar-environments-short">
+</p>
+
+## Loading variables
+
+Variables are stored in `.env` files, and loaded using the `--env` option.
+
+Here's what a `.env` file might look like:
+
+```bash
+# file: dev.env
+API_KEY="dev-api-key"
+ENV_NAME="dev"
+BASE_URL="https://${ENV_NAME}.example.com"
+```
+
+To make these variables available in the UI, you can load them using the `--env` option:
+
+```bash
+posting --env dev.env
+```
+
+You can load multiple `.env` files by specifying the `--env` option multiple times:
+
+```bash
+posting --env dev.env --env shared.env
+```
+
+This allows you to build up a set of variables which are common to all environments, and then override them for specific environments.
+
+## Using environment variables
+
+By default, Posting will only use variables defined in `.env` files that have been explicitly loaded using the `--env` option.
+
+If you want to permit using environment variables that exist on the host machine (i.e. those which are not defined in any `.env` files), you must set the `use_host_environment` config option to `true` (or set the environment variable `POSTING_USE_HOST_ENVIRONMENT=true`).
+
+## Practical example
+
+Imagine you're testing an API which exists in both `dev` and `prod` environments.
+
+The `dev` and `prod` environments share some common variables, but differ in many ways too.
+We can model this by having a single `shared.env` file which contains variables which are shared between environments, and then a `dev.env` and `prod.env` file which contain environment specific variables.
+
+```bash
+# file: shared.env
+API_PATH="/api/v1"
+ENV_NAME="shared"
+
+# file: dev.env
+API_KEY="dev-api-key"
+ENV_NAME="dev"
+BASE_URL="https://${ENV_NAME}.example.com"
+
+# file: prod.env
+API_KEY="prod-api-key"
+ENV_NAME="prod"
+BASE_URL="https://${ENV_NAME}.example.com"
+```
+
+When working in the `dev` environment, you can then load all of the shared variables and all of the development environment specific variables using the `--env` option:
+
+```bash
+posting --env shared.env --env dev.env
+```
+
+This will load all of the shared variables from `shared.env`, and then load the variables from `dev.env`. Since `ENV_NAME` appears in both files, the value from the `dev.env` file will be used since that was the last one specified.
+
+Note that you do *not* need to restart to load changes made to these files,
+so you can open and edit your env files in an editor of your choice alongside Posting.
+However, autocompletion and variable highlighting will not update until Posting is restarted.
+
+### Environment specific config
+
+Since all Posting configuration options can also be specified as environment variables, we can also put environment specific config inside `.env` files. There's a dedicated "Configuration" section in this document which covers this in more detail.
+
+For example, if you wanted to use a light theme in the prod environment (as a subtle reminder that you're in production!), you could set the environment variable `POSTING_THEME=solarized-light` inside the `prod.env` file.
+
+Note that configuration files take precedence over environment variables, so if you set a value in both a `.env` file and a `config.yaml`, the value from the `config.yaml` file will be used.

docs/guide/help_system.md

@@ -0,0 +1,13 @@
+## Overview
+
+Posting has a *built-in help system*, which can be used to get information about the currently focused widget.
+
+### Getting help for the focused widget
+
+With a widget focused, press `f1` to open a help window for that widget.
+
+<img width="1229" alt="image" src="https://github.com/user-attachments/assets/707be55f-6dfc-4faf-b9f3-fe7bc5422008">
+
+Most widgets offer more keybindings and functionality than meets the eye, and more than what is shown in the application footer.
+
+The help window explains how to use the focused widget, and lists all of the keybindings offered by it.

docs/guide/importing.md

@@ -0,0 +1,19 @@
+## Overview
+
+Posting currently supports importing from OpenAPI specs.
+
+Support for other API formats will be added in future updates.
+
+## Importing from OpenAPI
+
+!!! example "This feature is experimental."
+
+Posting can convert OpenAPI 3.x specs into collections.
+
+To import an OpenAPI Specification, use the `posting import path/to/openapi.yaml` command.
+
+You can optionally supply an output directory.
+
+If no output directory is supplied, the default collection directory will be used.
+
+Posting will attempt to build a file structure in the collection that aligns with the URL structure of the imported API.