From 993d344d1ecab227e4d3bfc85ef248f884484b70 Mon Sep 17 00:00:00 2001 From: Elliott Steer <117514332+essteer@users.noreply.github.com> Date: Sat, 28 Sep 2024 11:42:22 +0800 Subject: [PATCH] docs: Update pagelinks and status info (#21) * chore: Update PyPI badge to use dynamic version and add #title to top buttons * chore: Add Docker image status info to documentation page --- README.md | 14 +++++++------- docs/deployment.md | 39 +++++++++++++++++++-------------------- docs/development.md | 22 +++++++++++----------- docs/docker.md | 31 ++++++++++++++++++------------- 4 files changed, 55 insertions(+), 51 deletions(-) diff --git a/README.md b/README.md index 826d052..dd94c8e 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@

- +

@@ -70,12 +70,12 @@ $ curl -X GET 'https://masquer.fly.dev/masq?ua=true&rf=true' -H 'accept: applica Refer to the [API docs](`https://masquer.fly.dev/docs`) for other examples, or see [more details below](#examples) in the package documentation.

- +

## Python package -[![](https://img.shields.io/badge/PyPI-masquer-3775A9.svg?style=flat&logo=PyPI&logoColor=white)](https://pypi.org/project/masquer/) +[![PyPI](https://img.shields.io/badge/PyPI-masquer-3775A9.svg?style=flat&logo=PyPI&logoColor=white)](https://pypi.org/project/masquer/) ### Installation @@ -190,12 +190,12 @@ To get the header-data with randomly selected user-agent and/or referer data, pa ```

- +

## Git repository -[![](https://img.shields.io/badge/GitHub-masquer-181717.svg?flat&logo=GitHub&logoColor=white)](https://github.com/essteer/masquer) +[![GitHub](https://img.shields.io/badge/GitHub-masquer-181717.svg?flat&logo=GitHub&logoColor=white)](https://github.com/essteer/masquer) Clone the `masquer` repo for the full source code, including the FastAPI app used to host the [API](#api) introduced above. @@ -262,7 +262,7 @@ Then follow the instructions FastAPI provides in the terminal. To view the API's interactive documentation, run the app and navigate to `http://127.0.0.1:8000/docs` or `http://127.0.0.1:8000/redoc`.

- +

## Docker image @@ -286,5 +286,5 @@ $ docker run -d --name masquer -p 8000:8000 essteer/masquer Then interact as per the [API instructions](#api) above.

- +

diff --git a/docs/deployment.md b/docs/deployment.md index 5e2b54e..f7ce537 100644 --- a/docs/deployment.md +++ b/docs/deployment.md @@ -34,6 +34,8 @@ Asset updates are performed on a regular basis to keep the user-agent and refere A typical workflow up to the testing stage is outlined in this section. +### Create feature branch + Activate the virtual environment then create and checkout a new branch such as `asset-update`. ```console @@ -50,7 +52,7 @@ For an asset update, follow the instructions detailed under the [`Asset updates` If the process is successful and no issues arose, continue to the testing stage.

- +

## Test @@ -67,7 +69,7 @@ Ensure all tests are passing before proceeding further. ### API tests - +[![FastAPI](https://img.shields.io/badge/FastAPI-masquer-009688?style=flat&logo=FastAPI&logoColor=white)](https://masquer.fly.dev/docs) Once the unit tests have passed, run the FastAPI app from the project root directory in development mode: @@ -87,7 +89,7 @@ If the expected response is received, proceed to the Docker image tests. ### Docker image tests - +[![Docker](https://img.shields.io/badge/Docker-masquer-2496ED.svg?flat&logo=Docker&labelColor=555&logoColor=white)](https://hub.docker.com/r/essteer/masquer) Follow the steps detailed in [`docker.md`](https://github.com/essteer/masquer/blob/main/docs/docker.md) to build and test a Docker image locally. @@ -96,7 +98,7 @@ Once the image and container are confirmed as running successfully, repeat the A If each of the steps indicated above is successful, deployment can proceed to the next stage.

- +

## Version @@ -113,15 +115,13 @@ New: 1.2.2 This will automatically update the version number in `src/masquer/__about__.py`, which is where the version information in `pyproject.toml` is read from for the main `masquer` program, and in `src/api/main.py` for the API. -Manually update the version number in the PyPI icon at the top of [`README.md`](https://github.com/essteer/masquer/blob/main/README.md) to match the new version number. -

- +

## Format - +[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff) Add and commit the version changes to git. @@ -134,12 +134,12 @@ See the [`Formatting`](https://github.com/essteer/masquer/blob/main/docs/develop Push to GitHub.

- +

## Merge to `main` -[![](https://img.shields.io/badge/GitHub-masquer-181717.svg?flat&logo=GitHub&logoColor=white)](https://github.com/essteer/masquer) +[![GitHub](https://img.shields.io/badge/GitHub-masquer-181717.svg?flat&logo=GitHub&logoColor=white)](https://github.com/essteer/masquer) If the package build was successful, open a PR on GitHub to merge the updated package into `main` branch. @@ -148,13 +148,13 @@ GitHub workflows are in place to do a final format and test whenever a commit or See the [`GitHub Actions`](https://github.com/essteer/masquer/blob/main/docs/development.md#github-actions) section of [`development.md`](https://github.com/essteer/masquer/blob/main/docs/development.md) for more details.

- +

## Release and build Docker image -[![](https://img.shields.io/badge/GitHub-masquer-181717.svg?flat&logo=GitHub&logoColor=white)](https://github.com/essteer/masquer) - +[![GitHub](https://img.shields.io/badge/GitHub-masquer-181717.svg?flat&logo=GitHub&logoColor=white)](https://github.com/essteer/masquer) +[![Docker](https://img.shields.io/badge/Docker-masquer-2496ED.svg?flat&logo=Docker&labelColor=555&logoColor=white)](https://hub.docker.com/r/essteer/masquer) Assuming that the PR passed the GitHub Actions and the merge completed successfully, from the [main repo page](https://github.com/essteer/masquer) on GitHub click on the `Releases` heading then `Draft a new release`. @@ -169,7 +169,7 @@ The `docker.yaml` GitHub workflow will then build a Docker image of the new vers Follow the instructions in [`docker.md`](https://github.com/essteer/masquer/blob/main/docs/docker.md) to pull and test that the image is working as expected.

- +

## Build distribution @@ -187,12 +187,12 @@ dist/masquer-1.2.2-py3-none-any.whl ```

- +

## Publish to PyPI - +[![PyPI](https://img.shields.io/pypi/v/masquer?style=flat&logo=PyPI&logoColor=white&label=PyPI&labelColor=555&color=3776AB)](https://pypi.org/project/masquer/) After a successful build the package is ready to publish on PyPI: @@ -209,13 +209,12 @@ https://pypi.org/project/masquer/1.2.2/ ```

- +

## Deploy to production - - +[![Fly.io](https://img.shields.io/badge/Fly.io-masquer-24175B.svg?style=flat&labelColor=555&logo=flydotio&logoColor=white)](https://masquer.fly.dev/docs) From the project root directory, run the following command to deploy to production: @@ -226,5 +225,5 @@ $ fly deploy Visit the deployment at the link as prompted and test it via the API docs.

- +

diff --git a/docs/development.md b/docs/development.md index a97acdc..4332493 100644 --- a/docs/development.md +++ b/docs/development.md @@ -18,7 +18,7 @@ See also the main [`README.md`](https://github.com/essteer/masquer/blob/main/REA ## Git repository -[![](https://img.shields.io/badge/GitHub-masquer-181717.svg?flat&logo=GitHub&logoColor=white)](https://github.com/essteer/masquer) +[![GitHub](https://img.shields.io/badge/GitHub-masquer-181717.svg?flat&logo=GitHub&logoColor=white)](https://github.com/essteer/masquer) Clone the `masquer` repo for the full source code: @@ -51,7 +51,7 @@ The directory structure of the repo is as follows: ```

- +

## Asset updates @@ -75,12 +75,12 @@ In case of issues updating the assets, ensure all dependencies are installed and If using custom JSON data, the `update_assets()` function inside `update.py` can still be used to sync changes with the `assets.py` file inside the `masquer` package.

- +

## Docker - +[![Docker](https://img.shields.io/badge/Docker-masquer-2496ED.svg?flat&logo=Docker&labelColor=555&logoColor=white)](https://hub.docker.com/r/essteer/masquer) In production `masquer` is deployed from a Docker image that is also called `masquer` and is registered here on Docker hub: [`https://hub.docker.com/r/essteer/masquer`](https://hub.docker.com/r/essteer/masquer). @@ -98,12 +98,12 @@ During development — especially in the event of changes to the package dir A `docker.yaml` workflow is in place to build and publish a Docker image when a new release is made on the `main` branch — see the notes in [`deployment.md`](https://github.com/essteer/masquer/blob/main/docs/deployment.md) and [`docker.md`](https://github.com/essteer/masquer/blob/main/docs/docker.md) for more details.

- +

## Formatting - +[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff) Python files in `masquer` are formatted using Ruff. @@ -116,12 +116,12 @@ A pre-commit hook is configured in `.pre-commit-config.yaml` to check and format A GitHub action is configured in `.github/workflows/ruff.yaml` to run Ruff checks for any push or pull request to the `main` branch.

- +

## GitHub Actions -[![](https://img.shields.io/badge/GitHub-masquer-181717.svg?flat&logo=GitHub&logoColor=white)](https://github.com/essteer/masquer) +[![GitHub](https://img.shields.io/badge/GitHub-masquer-181717.svg?flat&logo=GitHub&logoColor=white)](https://github.com/essteer/masquer) GitHub actions are configured in `.github/workflows` and are in place for all pushes and pull requests for the `main` branch: @@ -131,7 +131,7 @@ GitHub actions are configured in `.github/workflows` and are in place for all pu A `docker.yaml` workflow is in place to build a new Docker image and publish it to Docker Hub whenever a new release is made on the `main` branch — see the [`deployment.md`](https://github.com/essteer/masquer/blob/main/docs/deployment.md) notes for more details.

- +

## Logs @@ -179,7 +179,7 @@ The following files are set up to record log messages: | `src/masquer` | `app.py` | |

- +

## Tests @@ -215,5 +215,5 @@ A GitHub action is configured in `.github/workflows/test.yaml` to run the unit t The tests are run on a matrix basis for Linux (Ubuntu), macOS and Windows on Python versions from `3.9` to `3.12` (inclusive).

- +

diff --git a/docs/docker.md b/docs/docker.md index b167c82..1be2342 100644 --- a/docs/docker.md +++ b/docs/docker.md @@ -1,5 +1,12 @@

Masquer — Docker notes

+

+ + + + +

+

Notes for use in creating, testing, and publishing the masquer Docker image.

@@ -19,7 +26,7 @@ See also the main [`README.md`](https://github.com/essteer/masquer/blob/main/REA ## Overview - +[![Docker](https://img.shields.io/badge/Docker-masquer-2496ED.svg?flat&logo=Docker&labelColor=555&logoColor=white)](https://hub.docker.com/r/essteer/masquer) In production `masquer` is deployed from a Docker image that is also called `masquer` and is registered here on Docker hub: [`https://hub.docker.com/r/essteer/masquer`](https://hub.docker.com/r/essteer/masquer). @@ -28,9 +35,8 @@ The files used to configure the Docker image are both in the project root direct - `Dockerfile`: specifies the steps and commands to execute in the Docker image build process, as well as the top-level directory to include in the image — in this case, that is the `src` directory - `.dockerignore`: specifies files and directories to exclude from the Docker image build -

- +

## Local development @@ -65,7 +71,7 @@ If the build is successful, a container can then be run using the image to test Note the first three characters of the image's `sha256` for subsequent use — in this case `1c3`.

- +

### Test container @@ -92,12 +98,12 @@ CONTAINER ID IMAGE COMMAND CREATED STATUS The first several characters of the container's `sha256` are displayed under the `CONTAINER ID` column, as are the first three characters of the image's `sha256`.

- +

### Test API on container - +[![FastAPI](https://img.shields.io/badge/FastAPI-masquer-009688?style=flat&logo=FastAPI&logoColor=white)](https://masquer.fly.dev/docs) With the container running, test a few API calls with different arguments and verify that the expected output is received, for example: @@ -108,7 +114,7 @@ $ curl -X GET 'http://127.0.0.1:8000/masq?ua=true&rf=true&hd=false' -H 'accept: ```

- +

### Check logs on container @@ -123,7 +129,6 @@ $ docker exec -it 392 sh # 'sh' runs the basic shell If successful, the terminal prompt should now display the location on the container (above, `/usr/src/app/src`). - Logs should be created on the container at `/usr/src/app/logs/app.log` — if they are not present then first make sure the path stated here is up to date with the path in the `Dockerfile`. Change to the `logs` directory and `cat` the `app.log` contents — output similar to the lines displayed below should be visible, that relate to the previous API test calls. @@ -144,7 +149,7 @@ $ ```

- +

### Clean up @@ -168,19 +173,19 @@ Deleted: sha256:1c3642fd9d54d5870f1ed9dfdaf75d208bee648d15ba87c6de05ja4c5c069512 ```

- +

## GitHub Action -[![](https://img.shields.io/badge/GitHub-masquer-181717.svg?flat&logo=GitHub&logoColor=white)](https://github.com/essteer/masquer) +[![GitHub](https://img.shields.io/badge/GitHub-masquer-181717.svg?flat&logo=GitHub&logoColor=white)](https://github.com/essteer/masquer) A `docker.yaml` workflow is in place to build a new Docker image and publish it to Docker Hub whenever a new release is made on the `main` branch. -The image will be published as the latest image version listed at [`https://hub.docker.com/r/essteer/masquer`](https://hub.docker.com/r/essteer/masquer). +The image will be published as the latest image version listed at [`https://hub.docker.com/r/essteer/masquer`](https://hub.docker.com/r/essteer/masquer). For this reason, the image must be tested locally via the steps provided in this document before a new release is made to ensure that it works correctly.

- +