mirror of
https://github.com/kevinveenbirkenbach/computer-playbook.git
synced 2026-11-06 02:54:26 +00:00
docs: remove README.md files under docs/ and add lint check
Replace per-directory README.md index files with automatic glob toctree in root index.rst (docs/**). Add lint test that fails if any README.md appears under docs/. Document the no-README rule in documentation.md. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
kevinveenbirkenbachandClaude Sonnet 4.6 committed
1 parent
846e975876
commit
dca1eb69c7
24 files changed
+93
-198
No files matched your search
@@ -64,15 +64,14 @@ Try [Infinito.Nexus](https://infinito.nexus) – sign up in seconds, explore the
|
||||
|
||||
For the full development setup, contribution workflow, testing, and coding standards, see [CONTRIBUTING.md](CONTRIBUTING.md).
|
||||
|
||||
---
|
||||
|
||||
## License ⚖️
|
||||
|
||||
Infinito.Nexus is distributed under the **Infinito.Nexus Community License (Non-Commercial)**. Please see [LICENSE.md](LICENSE.md) for full terms.
|
||||
|
||||
---
|
||||
## 🛡️ Security
|
||||
|
||||
For security reporting and disclosure, see [SECURITY.md](SECURITY.md).
|
||||
|
||||
## Support and Contact 💼
|
||||
|
||||
For expert installation, contact details, and project participation, see [SUPPORT.md](SUPPORT.md).
|
||||
For security reporting and disclosure, see [SECURITY.md](SECURITY.md).
|
||||
@@ -1,12 +0,0 @@
|
||||
# Agent Instructions
|
||||
|
||||
Use this directory as the index for the detailed agent guidance referenced by [AGENTS.md](../../AGENTS.md).
|
||||
For contributor-side code structure and repository wiring, see [Code](../contributing/code/README.md).
|
||||
|
||||
## MUST Read in Order
|
||||
|
||||
You MUST read these files in the given order before acting on any task:
|
||||
|
||||
1. Read [Action](action/README.md) first for commit, development, debugging, iteration, and pull-request workflows.
|
||||
2. Read [Files](files/README.md) for file-specific implementation guidance such as role `style.css`, `javascript.js`, and Playwright role files.
|
||||
3. Read [Meta](meta/README.md) for purpose, help, ethics, and about references.
|
||||
@@ -1,15 +0,0 @@
|
||||
# Action
|
||||
|
||||
Use this section for operational agent workflows.
|
||||
|
||||
## MUST Read in Order
|
||||
|
||||
You MUST read the relevant files below before performing the matching action:
|
||||
|
||||
1. Read [Commit](commit.md) BEFORE you create a commit.
|
||||
2. Read [Refactor](refactor.md) AFTER every commit.
|
||||
3. Read [Role Files](../files/role/README.md) BEFORE you work on role-local frontend files such as `style.css` or `javascript.js`.
|
||||
4. Read [Development](develop.md) BEFORE you work on new apps or feature changes.
|
||||
5. Read [Iteration](iteration.md) BEFORE you cycle through local deploy retries.
|
||||
6. Read [Debugging](debug.md) BEFORE you investigate failures.
|
||||
7. Read [Pull Requests](pull-request.md) BEFORE you write a PR description.
|
||||
@@ -1,10 +0,0 @@
|
||||
# Files
|
||||
|
||||
Use this section for file-specific agent guidance.
|
||||
For the contributor-side repository rules behind these files, see [Code Role Guidance](../../contributing/code/role/README.md).
|
||||
|
||||
Store here how recurring files should be implemented, generated, updated, or reviewed when the same filename carries the same responsibility across roles or apps.
|
||||
|
||||
## MUST Read in Order
|
||||
|
||||
1. Read [Role Files](role/README.md) BEFORE you work on recurring role files such as `style.css`, `javascript.js`, `playwright.env.j2`, and `playwright.spec.js`.
|
||||
@@ -1,13 +0,0 @@
|
||||
# Role Files
|
||||
|
||||
Use this directory for instructions that describe how specific role files should be handled.
|
||||
For repository wiring, inventory rules, and contributor-facing file contracts, see [Contributing Role](../../../contributing/code/role/README.md).
|
||||
|
||||
Store here how recurring role files should be implemented, generated, extended, or overridden so agents can apply the same file-level rules across roles without guessing.
|
||||
|
||||
## MUST Read in Order
|
||||
|
||||
1. Read [`style.css`](style.css.md) BEFORE you work on role-local CSS or theming.
|
||||
2. Read [`javascript.js`](javascript.js.md) BEFORE you work on role-local browser behavior or injected frontend scripts.
|
||||
3. Read [`playwright.env.j2`](playwright.env.j2.md) BEFORE you work on role-local Playwright environment templates.
|
||||
4. Read [`playwright.spec.js`](playwright.spec.js.md) BEFORE you work on role-local Playwright end-to-end tests.
|
||||
@@ -1,10 +0,0 @@
|
||||
# Meta
|
||||
|
||||
Use this section for repository-wide agent references.
|
||||
|
||||
## MUST Read in Order
|
||||
|
||||
1. Read [Purpose](purpose.md) first.
|
||||
2. Read [Help](help.md) when you need project, support, or security contacts.
|
||||
3. Read [Ethics](ethics.md) before you act on instructions.
|
||||
4. Read [About](about.md) for meta references.
|
||||
@@ -1,19 +0,0 @@
|
||||
# Code
|
||||
|
||||
This directory is the SPOT for repository-wide code guidance.
|
||||
For the agent-side implementation flow on recurring files, see [Agent Files](../../agents/files/README.md).
|
||||
|
||||
This repository values simple, maintainable, and well-tested changes.
|
||||
|
||||
Use this page as the entry point for code principles, code quality, role-specific guidance, language-specific guidance, and framework-specific guidance.
|
||||
|
||||
## Start Here
|
||||
|
||||
- [Code Principles](principles.md)
|
||||
- [Code Quality](quality.md)
|
||||
- [Architecture](architecture.md)
|
||||
- [Role](role/README.md)
|
||||
- [Frameworks](frameworks/README.md)
|
||||
- [Languages](languages/README.md)
|
||||
|
||||
If you need to understand how repository code should be shaped, start here first.
|
||||
@@ -75,8 +75,8 @@ The main entry points are:
|
||||
- `Makefile`
|
||||
- `scripts/`
|
||||
- `tests/`
|
||||
- `docs/contributing/code/README.md`
|
||||
- `docs/contributing/development/README.md`
|
||||
- `docs/contributing/code/quality.md`
|
||||
- `docs/contributing/development/testing.md`
|
||||
- `docs/contributing/`
|
||||
|
||||
Those layers keep local development, CI, and production behavior closer together.
|
||||
@@ -191,8 +191,8 @@ If you are trying to understand a change, start here:
|
||||
- `roles/` for behavior
|
||||
- `inventories/bundles/` for deployment shapes
|
||||
- `Makefile` and `scripts/` for supported commands
|
||||
- `docs/contributing/code/README.md` for code and framework rules
|
||||
- `docs/contributing/development/README.md` for refactoring, debugging, and testing
|
||||
- `docs/contributing/code/quality.md` for code and framework rules
|
||||
- `docs/contributing/development/testing.md` for refactoring, debugging, and testing
|
||||
- `docs/contributing/` for workflow and constraints
|
||||
- `tests/` for the expected contracts
|
||||
|
||||
|
||||
@@ -1,12 +0,0 @@
|
||||
# Frameworks
|
||||
|
||||
This directory is the SPOT for framework-specific guidance.
|
||||
|
||||
Use this page as the entry point for framework rules that apply to shared implementation surfaces.
|
||||
|
||||
## Start Here
|
||||
|
||||
- [Ansible](ansible.md)
|
||||
- [Makefile](Makefile.md)
|
||||
|
||||
If you are working on a framework-specific rule, start here before going deeper.
|
||||
@@ -1,11 +0,0 @@
|
||||
# Languages
|
||||
|
||||
This directory is the SPOT for language-specific guidance.
|
||||
|
||||
Use this page as the entry point for language rules that apply across the repository.
|
||||
|
||||
## Start Here
|
||||
|
||||
- [Shell](shell.md)
|
||||
|
||||
If you are working on a language-specific rule, start here before going deeper.
|
||||
@@ -24,4 +24,4 @@ You MUST apply these repo-wide rules when you add, move, or review files:
|
||||
- Treat structural hubs such as `roles/`, `cli/`, `tests/unit/plugins/filter`, `tests/unit/roles`, `inventories/bundles/servers`, `inventories/bundles/workstations`, `plugins/filter`, `plugins/lookup`, `group_vars/all`, and `.github/workflows` as intentional exceptions when they are used to organize the tree.
|
||||
- You SHOULD prefer smaller, more focused folders over dumping many unrelated files into one directory.
|
||||
|
||||
For refactoring guidance, see [Development](../development/README.md).
|
||||
For refactoring guidance, see [Development](../development/refactoring.md).
|
||||
@@ -1,15 +0,0 @@
|
||||
# Role
|
||||
|
||||
This directory is the SPOT for role-specific code guidance.
|
||||
For the agent-side implementation and review workflow for the same files, see [Agent Role Files](../../../agents/files/role/README.md).
|
||||
|
||||
Use this page as the entry point for rules that apply to recurring role files and role-local implementation patterns.
|
||||
|
||||
## Start Here
|
||||
|
||||
- [`style.css`](style.css.md)
|
||||
- [`javascript.js`](javascript.js.md)
|
||||
- [`playwright.env.j2`](playwright.env.j2.md)
|
||||
- [`playwright.spec.js`](playwright.spec.js.md)
|
||||
|
||||
If you are working on recurring role files, start here before you go deeper.
|
||||
@@ -1,14 +0,0 @@
|
||||
# Development
|
||||
|
||||
This directory is the SPOT for development workflow guidance.
|
||||
|
||||
Use this page as the entry point for refactoring, testing, and debugging.
|
||||
|
||||
## Start Here
|
||||
|
||||
- [Supported Systems](systems.md)
|
||||
- [Refactoring](refactoring.md)
|
||||
- [Testing and Validation](testing.md)
|
||||
- [CI Failures and Debugging](debugging.md)
|
||||
|
||||
If you are unsure which development page you need, start here.
|
||||
@@ -7,4 +7,4 @@ Use this page when you reshape existing code without changing intended behavior.
|
||||
- If similar logic exists elsewhere in the project, you SHOULD refactor it toward a shared implementation.
|
||||
- You SHOULD separate mechanical cleanup from behavior changes when that lowers risk.
|
||||
|
||||
For related expectations, see [Code](../code/README.md).
|
||||
For related expectations, see [Code](../code/quality.md).
|
||||
@@ -2,12 +2,6 @@
|
||||
|
||||
All project documentation MUST be reachable at [docs.infinito.nexus](https://docs.infinito.nexus/).
|
||||
|
||||
## Markdown
|
||||
|
||||
- You MUST keep core information inside the repository, either in code or in `.md` files.
|
||||
- You MUST use `.md` files for commands, workflows, setup, and contributor guidance.
|
||||
- You MUST NOT use `.md` files to describe implementation logic that is already visible in the code.
|
||||
|
||||
## Comments
|
||||
|
||||
- You SHOULD write code so it is logical and self-explanatory and usually does not need comments.
|
||||
@@ -50,10 +44,16 @@ You MUST use [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119) keywords in all
|
||||
## Documentation Structure
|
||||
|
||||
### Markdown
|
||||
|
||||
- You SHOULD prefer `README.md` for directory-level documentation when a human-facing entry point already exists.
|
||||
- You MUST NOT place `README.md` files under `docs/`.
|
||||
Documentation files MUST be cross-linked to each other directly instead.
|
||||
All content under `docs/` is automatically indexed via the root `index.rst` toctree glob (`docs/**`) — no per-directory index files are needed.
|
||||
- You MUST keep core information inside the repository, either in code or in `.md` files.
|
||||
- You MUST use `.md` files for commands, workflows, setup, and contributor guidance.
|
||||
- You MUST NOT use `.md` files to describe implementation logic that is already visible in the code.
|
||||
|
||||
### Sphinx
|
||||
|
||||
- If a documentation directory does not already have a `README.md`, you SHOULD add an `index.rst` where it helps automated docs generation.
|
||||
- You MUST keep Sphinx-friendly directory indexes up to date so the published documentation can include new content without extra wiring.
|
||||
- The root `index.rst` uses a `:glob:` toctree (`docs/**`) to automatically include every documentation page.
|
||||
You MUST NOT add a separate `index.rst` or `README.md` inside any `docs/` subdirectory.
|
||||
- You MUST keep cross-links between `.md` files up to date so readers can navigate between related pages.
|
||||
@@ -1,16 +0,0 @@
|
||||
# Development Environment
|
||||
|
||||
This directory is the entry point for local setup, platform-specific instructions, and low-hardware guidance.
|
||||
|
||||
Use these pages together when preparing a machine for local development.
|
||||
|
||||
## Start Here
|
||||
|
||||
- [Development Environment Setup](setup.md)
|
||||
- [Environment Variables](variables.md)
|
||||
- [Low-Hardware Resources](hardware.md)
|
||||
- [Linux](platform/linux.md)
|
||||
- [macOS](platform/macos.md)
|
||||
- [Windows (WSL2)](platform/windows-wsl2.md)
|
||||
|
||||
If you are unsure where to begin, start with the setup guide and continue from there.
|
||||
@@ -79,4 +79,4 @@ Use this as a practical reference when you want to understand how local developm
|
||||
If you work on a machine with limited CPU, RAM, or disk space, use the guide at [Manage Low-Hardware Resources](hardware.md).
|
||||
The public article with the same topic is [Developing on PCs with Limited Resources](https://s.infinito.nexus/minpcdev).
|
||||
|
||||
For local deploy shortcuts and end-to-end checks, see [Development](../development/README.md).
|
||||
For local deploy shortcuts and end-to-end checks, see [Development](../development/testing.md).
|
||||
@@ -1,13 +0,0 @@
|
||||
# Contribution Flow
|
||||
|
||||
This directory is the entry point for the fork-first contribution process.
|
||||
|
||||
Use these pages together to understand how changes move from a branch in your fork to review and merge.
|
||||
|
||||
## Start Here
|
||||
|
||||
- [Workflow](workflow.md)
|
||||
- [Pull Request Templates](pull-request.md)
|
||||
- [Review Requirements](review.md)
|
||||
|
||||
If you are unsure where to begin, start with the workflow guide and continue in order.
|
||||
@@ -4,7 +4,7 @@ You MUST open a Pull Request only when it is ready for real review.
|
||||
|
||||
The matching Pull Request template is the SPOT for PR structure, required author input, and review context. You MUST use the guidance in [Pull Request Templates](pull-request.md) and orient your Pull Request to it.
|
||||
|
||||
The [Code](../code/README.md) page is the SPOT for repository-wide code quality expectations such as diff quality, maintainability, and conventions.
|
||||
The [Code](../code/quality.md) page is the SPOT for repository-wide code quality expectations such as diff quality, maintainability, and conventions.
|
||||
|
||||
In addition to the templates, keep these repository-wide review rules in mind:
|
||||
|
||||
|
||||
@@ -1,14 +0,0 @@
|
||||
# Tools
|
||||
|
||||
This directory is the entry point for contributor tooling and agent guidance.
|
||||
|
||||
Use these pages together when you work on the local runtime or on agent-specific contributor instructions.
|
||||
|
||||
## Start Here
|
||||
|
||||
- [Makefile Commands](makefile.md)
|
||||
- [Act Workflow Checks](act.md)
|
||||
- [Docker and Runtime Commands](docker.md)
|
||||
- [Agent Guidelines](agents.md)
|
||||
|
||||
If you are unsure where to begin, start with the Makefile guide for command discovery, the Docker guide for runtime context, or the agent guide for agent-specific workflow guidance.
|
||||
@@ -6,7 +6,7 @@ The canonical `make` command index now lives in [Makefile Commands](makefile.md)
|
||||
## Scope
|
||||
|
||||
- Use [Makefile Commands](makefile.md) when you want the concrete repository targets.
|
||||
- Use [Development](../development/README.md) for app-level local deploy flows and end-to-end checks.
|
||||
- Use [Development](../development/testing.md) for app-level local deploy flows and end-to-end checks.
|
||||
- Use [Testing and Validation](../development/testing.md) for lint, unit, integration, and Playwright guidance.
|
||||
|
||||
## Notes
|
||||
|
||||
@@ -122,5 +122,5 @@ Use the dedicated script READMEs for the underlying shell helpers, and use the d
|
||||
## Notes
|
||||
|
||||
- The commands use the current `INFINITO_DISTRO` setting from the environment where relevant.
|
||||
- For app-level local deploy flows and end-to-end checks, see [Development](../development/README.md).
|
||||
- For app-level local deploy flows and end-to-end checks, see [Development](../development/testing.md).
|
||||
- For validation strategy and Playwright guidance, see [Testing and Validation](../development/testing.md).
|
||||
@@ -1,4 +1,14 @@
|
||||
About
|
||||
===============================
|
||||
|
||||
.. markdown-include:: ./README.md
|
||||
.. markdown-include:: ./README.md
|
||||
|
||||
Documentation
|
||||
-------------
|
||||
|
||||
The following pages cover contribution guidelines, development workflows, agent instructions, and security references.
|
||||
|
||||
.. toctree::
|
||||
:glob:
|
||||
|
||||
docs/**
|
||||
@@ -0,0 +1,60 @@
|
||||
"""Lint check: no README.md files allowed under docs/.
|
||||
|
||||
Documentation files under docs/ MUST be linked to each other directly
|
||||
and are automatically indexed via the root index.rst toctree glob.
|
||||
README.md files in docs/ are therefore redundant and MUST NOT exist.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import subprocess
|
||||
import unittest
|
||||
from pathlib import Path
|
||||
|
||||
|
||||
def repo_root() -> Path:
|
||||
return Path(__file__).resolve().parents[2]
|
||||
|
||||
|
||||
def tracked_files(root: Path) -> list[Path]:
|
||||
try:
|
||||
out = subprocess.check_output(
|
||||
["git", "-C", str(root), "ls-files", "-z"],
|
||||
stderr=subprocess.STDOUT,
|
||||
)
|
||||
rel_paths = [p for p in out.decode("utf-8", errors="replace").split("\0") if p]
|
||||
return [root / rel for rel in rel_paths]
|
||||
except Exception:
|
||||
return [p for p in root.rglob("*") if p.is_file()]
|
||||
|
||||
|
||||
class TestNoReadmeInDocs(unittest.TestCase):
|
||||
def test_no_readme_md_under_docs(self) -> None:
|
||||
"""docs/ MUST NOT contain README.md files.
|
||||
|
||||
Documentation files are linked to each other directly and are
|
||||
automatically indexed via the root index.rst toctree glob.
|
||||
Add cross-links between .md files instead of using README.md as
|
||||
an index.
|
||||
"""
|
||||
root = repo_root()
|
||||
docs_root = root / "docs"
|
||||
|
||||
violations = [
|
||||
path.relative_to(root).as_posix()
|
||||
for path in tracked_files(root)
|
||||
if path.name == "README.md" and path.is_relative_to(docs_root)
|
||||
]
|
||||
|
||||
if violations:
|
||||
msg = (
|
||||
"README.md files are not allowed under docs/. "
|
||||
"Link docs files to each other directly — they are "
|
||||
"automatically indexed via the root index.rst toctree glob.\n"
|
||||
"Found:\n" + "\n".join(f" {v}" for v in sorted(violations))
|
||||
)
|
||||
self.fail(msg)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
Reference in new issue
Block a user