diff --git a/docs/index.md b/docs/index.md index 865769c..ba3f894 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,5 +1,68 @@ -# Hello, world! +# Dave's Documentation Publishing Machine -This is an index file for my docs as code thing. +This project allows me to learn continuous integration and continuous deployment practices for documentation. -I **love** docs as code! +I **love** docs as code! I'm really enjoying the multidisciplinary nature of setting up and operating the pipeline: + +* writing markdown +* operating stuff from the terminal +* working with git +* setting up stuff in GitHub +* writing workflows in YAML +* vibe coding node modules +* developing AI prompts +* operating APIs + +I feel like a real hacker! :) + +## The Pipeline + +Here's how the whole thing works. + +### First-time setup + +Prerequisites: a local clone of the repository, Git, Python with pip, and Node.js 22 or newer. + +Run all commands from the repository root. The commands below use PowerShell. + +1. Install mkDocs: ```pip install mkdocs``` +1. Install the AI review dependency: ```npm ci --prefix .github/ai-review``` +1. Create an _.env_ file in the repository root with your own API key and model: + + ```dotenv + OPENAI_API_KEY=your-api-key + OPENAI_MODEL=your-model-id + ``` + +### Contributing + +Follow these steps when you want to contribute to the docs. + +1. Pull _master_. +1. Create a new local branch. +1. Write. +1. Stage the changes (don't commit). +1. Run the AI preview: ```node --env-file=.env .\.github\ai-review\review.mjs --preview``` +1. Run ```mkdocs serve``` to check how your work looks on the generated site. Open in your browser. +1. Commit. +1. Create a PR for merging your branch to _master_. + +### Automatic PR checks + +A GitHub Actions workflow runs when a PR is created or when you push the PR branch. The workflow is defined in _.github\workflows\pr-checks.yml_. + +The AI review is skipped for PRs from forks. + +This happens automatically: + +1. Run MarkdownLint to validate the markdown. Only the _docs_ folder is validated. The workflow stops if it finds errors. +1. Run ```mkdocs build --strict``` to check that the site builds. If the build fails, the workflow stops. +1. Generate a diff of your changes against master. +1. Run the AI review (_.github\ai-review\review.mjs_) on the diff. +1. Post the AI review as a PR comment. Token consumption information appears in the GitHub Actions job summary. The AI review is advisory, findings do not block merging the PR. + +After I review the PR, I merge it manually. + +### Publishing + +A GitHub Actions workflow builds and publishes the site in GitHub Pages when changes to _docs/_ or _mkdocs.yml_ are pushed to _master_, including when a PR is merged. You can also run it manually from the Actions tab. The workflow is defined in _.github\workflows\builddocs.yml_. diff --git a/docs/stack.md b/docs/stack.md index ffc30e0..2710da0 100644 --- a/docs/stack.md +++ b/docs/stack.md @@ -1,33 +1,61 @@ # My Docs as Code stack -I'm using these tools in the pipeline. +This page details the tools used in the pipeline and my reasoning for choosing those tools. For details about the pipeline itself, see [the home page](index.md). ## Authoring -I write markdown files with **Notepad++**. +I write markdown and the associated infrastructure code with **Notepad++**. It's the simplest tool that I already had on my computer. It is sufficient for this small prototype. -I use the following plugins: +I use [AnotherMarkdown](https://github.com/ezyuzin/NppAnotherMarkdown) to preview the rendered markdown. -- [AnotherMarkdown](https://github.com/ezyuzin/NppAnotherMarkdown) +Future consideration: I will switch to VS Code for production projects as it provides a more integrated coding experience. -## Versioning +## Source control -I use Git on Windows locally. I host the repository on GitHub. +Locally, I use **Git for Windows**. The [remote repository](https://github.com/davidstula/docsmachine) lives on **GitHub**. -[Open the repository](https://github.com/davidstula/docsmachine) +I use **GitHub CLI** from a **PowerShell** terminal. I'm authenticated via a GitHub token (the classic type) and communicate through HTTPS. -To operate GitHub I use GitHub CLI in a PowerShell terminal. I'm authenticated via a Github token (the classic type) and communicating through HTTPS. +GitHub is the most obvious choice for learning continuous integration practices and tools, as it's widely used and has detailed documentation. -## Static site generator +## Creating outputs -I use [mkDocs](https://www.mkdocs.org/) to generate and serve a local version of the docs site. +I use **[mkDocs](https://www.mkdocs.org/)** to generate a static site. -## Automation +Locally, I use the mkDocs _serve_ function to preview the end result. On GitHub, I use mkDocs to generate the site in a GitHub Actions workflow. -A GitHub Action workflow executes on a pull request to the "master" branch. The workflow runs on an Ubuntu runner with Python and does the following: +mkDocs uses its default settings. -1. Install mkDocs. -1. Check out the master branch. -1. Run ```mkdocs build```. -1. Upload the resulting ```site``` folder to Github Pages as an artifact. -1. Deploy the pages. +I chose mkDocs randomly. I didn't want to spend time evaluating static side generators so I just picked the first one I found. + +Future consideration: For simple pipelines such as this, I would use Jekyll, which is already integrated in GitHub. + +## Publishing + +I use **GitHub Pages** to publish the generated site. + +A **GitHub Actions** workflow uses mkDocs to generate the output and publish it when changes to _docs/_ or _mkdocs.yml_ are pushed to _master_, including when a PR is merged. The workflow can also be run manually from the Actions tab. + +## Content review + +The documentation content goes through automated review. The following happens when a new pull request is created: + +1. **MarkdownLint** validates the markdown code. +1. **mkDocs** checks that the site builds with the _--strict_ option. +1. OpenAI's **GPT-5.6 Luna** LLM reviews the content for clarity. + +The AI review runs only if the markdown validation and build pass. It is skipped for PRs from forks. + +I chose MarkdownLint as it's available as a published GitHub action, is widely used, and has high ratings. + +I chose GPT-5.6 Luna as the model that does the review because it's cheap and provides decent quality of responses. + +### Local AI review + +The same Node.js module can be used locally with the ```--preview``` argument to generate an AI review of staged changes without having to commit the changes. + +### AI review stack + +A **Node.js** module orchestrates the AI review. It calls **OpenAI's JavaScript SDK** and uses GitHub CLI to post the review as a comment to the pull request. + +These are tools I was somewhat familiar with so they represent the obvious choice for learning.