📝 docs update

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023-present Justin Flannery <[email protected]>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -29,11 +29,14 @@ It uses the GitHub filesystem to display the contents of the textual GitHub repo
 It requires the `requests` library to be installed.
 
 ```python
+from typing import Any, ClassVar, List
+
 from rich.syntax import Syntax
 from textual import on
 from textual.app import App, ComposeResult
+from textual.binding import BindingType
 from textual.containers import Horizontal, VerticalScroll
-from textual.widgets import Footer, Header, Static
+from textual.widgets import DirectoryTree, Footer, Header, Static
 
 from textual_universal_directorytree import UniversalDirectoryTree
 
@@ -43,24 +46,24 @@ class UniversalDirectoryTreeApp(App):
  The power of upath and fsspec in a Textual app
  """
 
- BINDINGS = [
+ BINDINGS: ClassVar[List[BindingType]] = [
  ("q", "quit", "Quit"),
  ]
 
- def __init__(self, *args, path: str, **kwargs):
+ def __init__(self, path: str, *args: Any, **kwargs: Any):
  super().__init__(*args, **kwargs)
  self.universal_path = path
+ self.file_content = Static()
 
  def compose(self) -> ComposeResult:
  yield Header()
- self.directory_tree = UniversalDirectoryTree(path=self.universal_path)
- self.file_content = Static()
- yield Horizontal(self.directory_tree, VerticalScroll(self.file_content))
+ directory_tree = UniversalDirectoryTree(path=self.universal_path)
+ yield Horizontal(directory_tree, VerticalScroll(self.file_content))
  yield Footer()
 
- @on(UniversalDirectoryTree.FileSelected)
+ @on(DirectoryTree.FileSelected)
  def handle_file_selected(
- self, message: UniversalDirectoryTree.FileSelected
+ self, message: DirectoryTree.FileSelected
  ) -> None:
  """
  Do something with the selected file.

docs/contributing.md

@@ -1,65 +1,142 @@
 # Contributing
 
-## Quickstart
-
-```shell
-pipx install pre-commit
-pipx install hatch
-pre-commit install
-hatch env create
-hatch shell
+## Environment Setup
+
+> TIP: **pipx**
+>
+> This documentaion uses [pipx] to
+> install and manage non-project command line tools like `hatch` and
+> `pre-commit`. If you don't already have `pipx` installed, make sure to
+> see their [documentation](https://pypa.github.io/pipx/installation/).
+> If you prefer not to use `pipx`, you can use `pip` instead.
+
+1. Install [hatch](https://hatch.pypa.io/latest/)
+
+ ```shell
+ pipx install hatch
+ ```
+
+ > NOTE: **pre-commit**
+ >
+ > Hatch will attempt to set up pre-commit hooks for you using
+ > [pre-commit]. If you don't already,
+ > make sure to install pre-commit as well: `pipx install pre-commit`
+
+2. Build the Virtual Environment
+
+ ```shell
+ hatch env create
+ ```
+
+3. If you need to, you can link a hatch virtual environment to your IDE.
+ They can be located by name with the `env find` command:
+
+ ```shell
+ hatch env find default
+ ```
+
+4. Activate the Virtual Environment
+
+ ```shell
+ hatch shell
+ ```
+
+## Using Hatch
+
+### Hatch Cheat Sheet
+
+| Command Description | Command | Notes |
+| -------------------------- | -------------------------- | ---------------------------------------------- |
+| Run Tests | `hatch run cov` | Runs tests with `pytest` and `coverage` |
+| Run Formatting | `hatch run lint:fmt` | Runs `ruff` code formatter |
+| Run Linting | `hatch run lint:style` | Runs `ruff` code linter |
+| Run Type Checking | `hatch run lint:typing` | Runs `mypy` type checker |
+| Run All Static Analysis | `hatch run lint:all` | Runs `ruff` and `mypy` linters / type checkers |
+| Serve the Documentation | `hatch run docs:serve` | Serve the documentation using MkDocs |
+| Run the `pre-commit` Hooks | `hatch run lint:precommit` | Runs the `pre-commit` hooks on all files |
+
+### Hatch Explanation
+
+Hatch is a Python package manager. Its most basic use is as a standardized build-system.
+However, hatch also has some extra features which this project takes advantage of.
+These features include virtual environment management and the organization of common
+scripts like linting and testing. All the operations in hatch take place in one
+of its managed virtual environments.
+
+Hatch has a variety of environments, to see them simply ask hatch:
+
+```bash exec="on" result="markdown" source="tabbed-left" tabs="hatch CLI|Output"
+hatch env show
 ```
 
-## Tools
+That above command will tell you that there are five environments that
+you can use:
+
+- `default`
+- `docs`
+- `gen`
+- `lint`
+- `test`
+
+Each of these environments has a set of commands that you can run.
+To see the commands for a specific environment, run:
 
-This project makes use of a couple tools to streamline the development process:
-[pre-commit](https://pre-commit.com/) and [hatch](https://hatch.pypa.io/).
+```bash exec="on" result="markdown" source="tabbed-left" tabs="hatch CLI|Output"
+hatch env show default
+```
+
+Here we can see that the `default` environment has the following commands:
 
-### pre-commit
+- `cov`
+- `test`
 
-[pre-commit] is a tool to manage git-hooks scripts, which are useful
-for identifying simple issues before submission to code review.
+The one that we're interested in is `cov`, which will run the tests
+for the project.
 
-```commandline
-pipx install pre-commit
-pre-commit install
+```bash
+hatch run cov
 ```
 
-To use pre-commit, you must first install it. [pipx] is preferred, but you can also install with
-`pip`. Once [pre-commit] is installed, run `pre-commit install` to install the git-hooks scripts
-into the local repository. Done, now pre-commit will run automatically on git commit. To run it
-manually on your changed files run `pre-commit run` on your command line.
+Since `cov` is in the default environment, we can run it without
+specifying the environment. However, to run the `serve` command in the
+`docs` environment, we need to specify the environment:
 
-### hatch
+```bash
+hatch run docs:serve
+```
 
-[hatch](https://hatch.pypa.io/) is a tool to manage the packaging and distribution of Python packages. It also
-used to manage the virtual environment for the project and running common scripts.
+You can see what scripts are available using the `env show` command
 
-```commandline
-pipx install hatch
-hatch env create
-hatch run test
+```bash exec="on" result="markdown" source="tabbed-left" tabs="hatch CLI|Output"
+hatch env show docs
 ```
 
-## Commit Message Format
+## Committing Code
+
+This project uses [pre-commit] to run a set of
+checks on the code before it is committed. The pre-commit hooks are
+installed by hatch automatically when you run it for the first time.
 
-Releases for this project are handled entirely by CI/CD via Pull requests being merged into
-the `main` branch. Contributions follow the [gitmoji] standards with [conventional commits],
-orchestration is handled by the [semantic-release] tool.
+This project uses [semantic-versioning] standards, managed by [semantic-release].
+Releases for this project are handled entirely by CI/CD via pull requests being
+merged into the `main` branch. Contributions follow the [gitmoji] standards
+with [conventional commits].
 
-While you can denote other changes on your commit messages with gitmoji, the following
+While you can denote other changes on your commit messages with [gitmoji], the following
 commit message emoji prefixes are the only ones to trigger new releases:
 
-| Emoji | Shortcode | Description | Semver |
-| ----- | ----------- | --------------------------- | ------ |
-| 💥 | :boom: | Introduce breaking changes. | Major |
-| ✨ | :sparkles: | Introduce new features. | Minor |
-| 🐛 | :bug: | Fix a bug. | Patch |
-| 🚑 | :ambulance: | Critical hotfix. | Patch |
-| 🔒 | :lock: | Fix security issues. | Patch |
+| Emoji | Shortcode  | Description | Semver |
+| ----- | ------------- | --------------------------- | ------ |
+| 💥 | \:boom\: | Introduce breaking changes. | Major |
+| ✨ | \:sparkles\: | Introduce new features. | Minor |
+| 🐛 | \:bug\: | Fix a bug. | Patch |
+| 🚑 | \:ambulance\: | Critical hotfix. | Patch |
+| 🔒 | \:lock\: | Fix security issues. | Patch |
 
-Most features can be squash merged into a single commit. If you're working on a
-feature, your commit message might look like:
+Most features can be squash merged into a single commit on a pull-request.
+When merging multiple commits, they will be summarized into a single release.
+
+If you're working on a new feature, your commit message might look like:
 
 ```text
 ✨ New Feature Description
@@ -71,43 +148,43 @@ Bug fix commits would look like this:
 🐛 Bug Fix Description
 ```
 
-## Scripts
+If you're working on a feature that introduces breaking changes, your
+commit message might look like:
+
+```text
+💥 Breaking Change Description
+```
 
-All common scripts for this repository are managed by [hatch](#hatch).
+Other commits that don't trigger a release might look like this:
 
-```shell
-hatch run <script>
+```text
+📝 Documentation Update Description
+👷 CI/CD Update Description
+🧪 Testing Changes Description
+🚚 Moving/Renaming Description
+⬆️ Dependency Upgrade Description
 ```
 
-| Script | Script Description |
-| -------------- | ------------------------------------------------------- |
-| `format` | Code Formatting [black] and [ruff] |
-| `lint` | Code Linting [black] and [ruff] |
-| `check` | Type Checking with [mypy] |
-| `test` | Unit Testing with [pytest] |
-| `all` | Run multiple scripts: `format`, `lint`, `check`, `test` |
-| `docs-serve` | Documentation Serving [MkDocs] and [mkdocs-material] |
-| `requirements` | Lock File Updates with [pip-tools] |
+### Pre-Releases
 
-## Dependencies
+[semantic-release] supports pre-releases. To trigger a pre-release, you
+would merge your pull request into an `alpha` or `beta` branch.
 
-Dependencies are managed by [pip-tools / pip-compile](https://github.com/jazzband/pip-tools/).
-After updating dependencies in the `pyproject.toml` file, run the following to update the
-underlying `requirements.txt` files:
+### Specific Release Versions
 
-```shell
-hatch run requirements
-```
+In some cases you need more advanced control around what kind of release you
+need to create. If you need to release a specific version, you can do so by creating a
+new branch with the version number as the branch name. For example, if the
+current version is `2.3.2`, but you need to release a fix as `1.2.5`, you
+would create a branch named `1.2.x` and merge your changes into that branch.
+
+See the [semantic-release documentation] for more information about
+branch based releases and other advanced release cases.
 
-[pipx]: https://pipxproject.github.io/pipx/
+[pipx]: https://pypa.github.io/pipx/
 [pre-commit]: https://pre-commit.com/
 [gitmoji]: https://gitmoji.dev/
 [conventional commits]: https://www.conventionalcommits.org/en/v1.0.0/
 [semantic-release]: https://github.com/semantic-release/semantic-release
-[black]: https://github.com/psf/black
-[ruff]: https://github.com/charliermarsh/ruff
-[mypy]: https://mypy.readthedocs.io/en/stable/
-[pytest]: https://docs.pytest.org/en/stable/
-[MkDocs]: https://www.mkdocs.org/
-[mkdocs-material]: https://squidfunk.github.io/mkdocs-material/
-[pip-tools]: https://github.com/jazzband/pip-tools/
+[semantic-versioning]: https://semver.org/
+[semantic-release documentation]: https://semantic-release.gitbook.io/semantic-release/usage/configuration#branches