Github Docs Cookiecutter

Author: Jared Cook
Version: 0.1.0

Overview:

Template cookiecutter project for Github Pages (Jekyll). Skip the boring stuff and get to the work that matters.

---

Usage Examples:

Example: Pull from main branch.

1. Pull Project with cookiecutter command:

$ cookiecutter git@github.com:jcook3701/github-docs-cookiecutter.git  

Example: Pull from develop branch.

1. Pull code from development branch while testing updates.

$ cookiecutter git@github.com:jcook3701/github-docs-cookiecutter.git --checkout develop  

Advance Examples:

Note: The real intention of this project is to call it as a hook within other cookiecutter projects as shown below.
Explanation: ansible-galaxy-cookiecutter template utilizes nutri-matic hooks to pull both this documentation template along with sphinx-cookiecutter template into generated project $(PROJECT_ROOT)/docs/.

Utilization of nutri-matic is the optimal way of integrating this template in projects.

---

Development Strategy:

Note: All Makefile commands are used in ci/cd to ensure that if they pass locally they should also pass once pushed to github.

🐍️ Build environment (.venv)

$ make install

🧬 Dependency Management (deptry)

$ make dependency-check

🛡️ Security Audit (pip-audit)

$ make security

🎨 Formatting (black)

$ make format-check

$ make format-fix

🔍 Linting (jinja2-cli, ruff, tomllint, & yaml-lint)

$ make lint-check

$ make lint-fix

🎓 Spellchecking (codespell)

$ make spellcheck

🧠 Typechecking (mypy)

$ make typecheck

🧪 Testing (pytest)

$ make test

🚀 Release (git tag)

$ make release

❓ Build Help

$ make help

Commit Help:

Note: Commits are required to be conventional git commit message. This helps with the auto-generation of the changelog files and is enforced by pre-commit.
example:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

• <type>: A required noun that describes the nature of the change.
• [optional scope]: An optional phrase within parentheses that specifies the part of the codebase being affected (e.g., fix(parser):).
• <description>: A required short, imperative-mood summary of the changes.
• [optional body]: A longer description providing additional context and "what and why" details.
• [optional footer(s)]: Used for adding meta-information, such as issue references (Fixes #123) or indicating breaking changes.

---

Requirements:

1. Python 3.11

$ sudo apt install python3.11

2. rustup
   Note: I found that it is easiest to use rustup to manage rustc and cargo but this is not required.
   Example: Install rustup with the following:

$ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

3. git-cliff
   Note: git-cliff can generate changelog files from the Git history by utilizing conventional commits as well as regex-powered custom parsers.

$ cargo install git-cliff

---

Authors Notes:

1. This code currently works with cookiecutter 1.7 from Ubuntu's apt repositories.