docs: format and lint README

Author: jgfranco17

.markdownlint.yaml

@@ -0,0 +1,4 @@
+---
+MD013:
+  tables: false
+  line_length: 110

.pre-commit-config.yaml

@@ -15,6 +15,12 @@ repos:
       - id: detect-private-key
       - id: requirements-txt-fixer
 
+  - repo: https://github.com/igorshubovych/markdownlint-cli
+    rev: v0.31.0
+    hooks:
+      - id: markdownlint
+        args: [--config, ".markdownlint.yaml"]
+
   - repo: https://github.com/codespell-project/codespell.git
     rev: v2.1.0
     hooks:

README.md

@@ -1,6 +1,4 @@
-<h1 align="center">FizzBuzz API</h1>
-
-<div align="center">
+# FizzBuzz API
 
 ![STATUS](https://img.shields.io/badge/status-active-brightgreen?style=for-the-badge)
 ![LICENSE](https://img.shields.io/badge/license-MIT-blue?style=for-the-badge)
@@ -12,39 +10,46 @@
 ## 📝 Table of Contents
 
 - [About](#about)
-- [Getting Started](#getting_started)
+- [Getting Started](#getting-started)
 - [Usage](#usage)
 - [Testing](#testing)
 - [Authors](#authors)
 
-## 🔎 About <a name = "about"></a>
+## About
 
-The whole point of this project is to showcase the concepts of SWE and DevOps that I have learned so far. This project features CI/CD
-workflows and automations, unittesting, and containerization. Git & Github were used as the VCS, and a Docker Hub image is published
-for container deployment. I dub this as "FizzBuzz-as-a-Service".
+The whole point of this project is to showcase the concepts of SWE and DevOps that I have learned
+so far. This project features CI/CD workflows and automations, unittesting, and containerization.
+Git & Github were used as the VCS, and a Docker Hub image is published for container deployment.
+I dub this as "FizzBuzz-as-a-Service".
 
-This program aims to create a FastAPI-based microservice that solves the classic FizzBuzz programming problem. The FizzBuzz problem is a
-common coding challenge often used in interviews to evaluate a candidate's basic programming skills. The task is to write a program that
-prints numbers from 1 to n; however, for multiples of 3, it should print "Fizz" instead of the number, for multiples of 5, it should
-print "Buzz," and for numbers that are multiples of both 3 and 5, it should print "FizzBuzz". The FizzBuzz Microservice API provides a
-simple HTTP-based API to solve the FizzBuzz problem. It allows users to make requests to the microservice and receive the FizzBuzz
-sequence as a response. This microservice can be easily integrated into other applications or used for testing and learning purposes.
+This program aims to create a FastAPI-based microservice that solves the FizzBuzz algorithm. The
+FizzBuzz problem is a common coding challenge often used in interviews to evaluate a candidate's
+basic programming skills. The task is to write a program that prints numbers from `1` to `n`;
+however, for multiples of `3`, it should print `"Fizz"` instead of the number, for multiples of
+`5`, it should print `"Buzz"`, and for numbers that are multiples of both `3` and `5`, it would
+print `"FizzBuzz"`. The FizzBuzz API provides a simple HTTP API to solve the FizzBuzz problem.
+It allows users to make requests to the microservice and receive the resulting FizzBuzz sequence
+as a response. This microservice can be easily integrated into other applications or used for
+testing and learning purposes.
 
-## 🏁 Getting Started <a name = "getting_started"></a>
+## Getting Started
 
-These instructions will get you a copy of the project up and running on your local machine for development and testing purposes.
+These instructions will get you a copy of the project up and running on your local machine for
+development and testing purposes.
 
 ### Prerequisites
 
-Before running the FizzBuzz Microservice API, make sure you have the following prerequisites installed:
+Before running the FizzBuzz Microservice API, make sure you have the following prerequisites
+installed:
 
 - [Python 3.9](https://www.python.org/downloads/) or above
 - [Poetry](https://python-poetry.org/) dependency manager
 - [Just](https://github.com/casey/just) command runner
 
 ### Installing
 
-To get started with this project, clone the repository to your local machine and install the required dependencies.
+To get started with this project, clone the repository to your local machine and install the required
+dependencies.
 
 ```bash
 git clone https://github.com/jgfranco17/fizzbuzz-api.git
@@ -53,7 +58,7 @@ poetry install
 poetry shell
 ```
 
-## 🚀 Usage <a name = "usage"></a>
+## Usage
 
 ### Dev mode
 
@@ -69,7 +74,9 @@ just run-debug
 
 ### Build with Docker
 
-To run the microservice in a container, the package comes with both a Dockerfile and a Compose YAML configuration. Run either of the following to get the API launched in a container; by default, the API will be set to listen on port 5050 for the Compose.
+To run the microservice in a container, the package comes with both a Dockerfile and a Compose YAML
+configuration. Run either of the following to get the API launched in a container; by default, the
+API will be set to listen on port `5050` for the Compose.
 
 ```bash
 # Plain Docker build
@@ -88,45 +95,48 @@ docker pull jgfranco17/fizzbuzz-api:latest
 
 ### Calling the API
 
-Once the microservice is launched, the API is now reachable. To get a FizzBuzz sequence, simply send a `GET` request to the server, with the number as a parameter.
+Once the microservice is launched, the API is now reachable. To get a FizzBuzz sequence, simply send
+a `GET` request to the server, with the number as a parameter.
 
 ```bash
 curl http://localhost:<PORT>/fizzbuzz?number=<number>
 ```
 
-## 🔧 Testing <a name = "testing"></a>
+## Testing
 
 ### Running unittest suite
 
-In order to run diagnostics and unittests, first install the testing dependencies. This will allow you to utilize the full capacity of the
-test modules we have built. To run the full test suite, run the Justfile command as follows:
+In order to run diagnostics and unittests, first install the testing dependencies. This will allow
+you to utilize the full capacity of the test modules we have built. To run the full test suite,
+run the Justfile command as follows:
 
 ```bash
 just pytest
 ```
 
 ### Using PyTest
 
-You can run these tests using the [PyTest](https://docs.pytest.org/en/7.3.x/) CLI tool. To run all tests in the directory containing the test
-files, navigate to the directory and enter `pytest` in the command line; for added verbosity, add the `-vv` flag after. To run a specific test
-file, enter `pytest <filename>`.
+You can run these tests using the [PyTest](https://docs.pytest.org/en/7.3.x/) CLI tool. To run all
+tests in the directory containing the test files, navigate to the directory and enter `pytest` in
+the command line. Prepending `just` ensures that the Pytest used is the one from the current
+dev environment.
 
 ```bash
 # Run all tests in the testing module with verbose detail
-pytest -vv
+just pytest -vv
 
 # Or, run a specific test file
-cd ./tests
-pytest -v <filename>.py
+just pytest -v <filepath>
 ```
 
 This will run the specified test module and generates a detailed result report in the terminal.
 
 ### Running Behave suite
 
-Behave is a Python-based BDD framework that allows you to write tests in a natural language style using Gherkin syntax. Gherkin uses a simple,
-human-readable format that is easy for both technical and non-technical stakeholders to understand. Behave translates these plain-text scenarios
-into executable code, allowing teams to collaborate on defining and implementing software features.
+Behave is a Python-based BDD framework that allows you to write tests in a natural language style
+using Gherkin syntax. Gherkin uses a simple, human-readable format that is easy for both technical
+and non-technical stakeholders to understand. Behave translates these plain-text scenarios into
+executable code, allowing teams to collaborate on defining and implementing software features.
 
 To run the full Behave suite, run the Justfile command as follows:
 
@@ -138,11 +148,12 @@ This will run the specified test module and generates a detailed result report i
 
 #### Why BDD?
 
-Behavior-Driven Development (BDD) is a software development methodology that focuses on collaboration among developers, QA, and non-technical
-stakeholders. BDD aims to enhance communication and understanding by using natural language descriptions of software behaviors and features.
-BDD allows teams to define the expected behavior of the software before implementation; clear specifications help developers focus on
-delivering features that meet business requirements. Non-technical team members can also easily understand and contribute to the specification
-process.
+Behavior-Driven Development (BDD) is a software development methodology that focuses on collaboration
+among developers, QA, and non-technical stakeholders. BDD aims to foster and enhance communication
+and understanding by using natural language descriptions of software behaviors and features. BDD
+allows teams to define the expected behavior of the software before implementation; clear specifications
+help developers focus on delivering features that meet business requirements. Non-technical team members
+can also easily understand and contribute to the specification process.
 
 For example, below is a demonstration of a simple test case for pinging the `/healthz` endpoint.
 
@@ -153,20 +164,34 @@ Scenario: Access health-check endpoint
     Then the response is returned with status code 200
 ```
 
-Using Gherkin allows us to run simple test cases without diving too deep into the technicals. As long as the test-writer is
-familiarized with the basic test steps that can be used, there is no need to use more complex testing frameworks for routine
-tests. Feel free to write your own Gherkin steps for this project!
+Using Gherkin allows us to run simple test cases without diving too deep into the technicals. As long
+as the test-writer is familiarized with the basic test steps that can be used, there is no need to use
+more complex testing frameworks for routine tests. Feel free to write your own Gherkin steps for this
+project!
 
 ### Load-testing with Locust
 
-Load testing is a type of performance testing that evaluates how a system behaves under a specific load. The primary goal is to ensure the
-system can handle expected user traffic and identify potential bottlenecks or performance issues before they affect end users. During load
-testing, the system is subjected to increasing numbers of simultaneous users or transactions to determine its capacity, stability, and
+Load testing is a type of performance testing that evaluates how a system behaves under a specific load.
+The primary goal is to ensure the system can handle expected user traffic and identify potential bottlenecks
+or performance issues before they affect end users. During load test execution, the system is subjected to
+increasing numbers of simultaneous users or transactions to determine its capacity, stability, and
 scalability.
 
-For this project, we use [Locust](https://locust.io/), an open-source load testing tool that is highly flexible and scalable, making it a
-popular choice for load testing web applications, APIs, and other services.
+For this project, we use [Locust](https://locust.io/), an open-source load testing tool that is highly
+flexible and scalable, making it a popular choice for load testing web applications, APIs, and other
+services.
+
+## CI/CD
+
+This project uses Github Actions for DevOps automations. On push to main, the following pipeline is enacted.
+
+- Run build and test
+- Codebase linting
+- Coverage reporting
+- Deployment to [hosting service](https://fizzbuzz-api.onrender.com/)
+
+Smoke tests and load tests are run periodically on schedule.
 
-## ✒️ Authors <a name = "authors"></a>
+## Authors
 
 - [Chino Franco](https://github.com/jgfranco17)