From dca1eb69c79f05894600127341e2039dd3ed13bf Mon Sep 17 00:00:00 2001 From: Kevin Veen-Birkenbach Date: Sun, 29 Mar 2026 21:16:15 +0200 Subject: [PATCH] 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 --- README.md | 7 +-- docs/agents/README.md | 12 ---- docs/agents/action/README.md | 15 ----- docs/agents/files/README.md | 10 ---- docs/agents/files/role/README.md | 13 ----- docs/agents/meta/README.md | 10 ---- docs/contributing/code/README.md | 19 ------- docs/contributing/code/architecture.md | 8 +-- docs/contributing/code/frameworks/README.md | 12 ---- docs/contributing/code/languages/README.md | 11 ---- docs/contributing/code/quality.md | 2 +- docs/contributing/code/role/README.md | 15 ----- docs/contributing/development/README.md | 14 ----- docs/contributing/development/refactoring.md | 2 +- docs/contributing/documentation.md | 18 +++--- docs/contributing/environment/README.md | 16 ------ docs/contributing/environment/setup.md | 2 +- docs/contributing/flow/README.md | 13 ----- docs/contributing/flow/review.md | 2 +- docs/contributing/tools/README.md | 14 ----- docs/contributing/tools/docker.md | 2 +- docs/contributing/tools/makefile.md | 2 +- index.rst | 12 +++- tests/lint/test_no_readme_in_docs.py | 60 ++++++++++++++++++++ 24 files changed, 93 insertions(+), 198 deletions(-) delete mode 100644 docs/agents/README.md delete mode 100644 docs/agents/action/README.md delete mode 100644 docs/agents/files/README.md delete mode 100644 docs/agents/files/role/README.md delete mode 100644 docs/agents/meta/README.md delete mode 100644 docs/contributing/code/README.md delete mode 100644 docs/contributing/code/frameworks/README.md delete mode 100644 docs/contributing/code/languages/README.md delete mode 100644 docs/contributing/code/role/README.md delete mode 100644 docs/contributing/development/README.md delete mode 100644 docs/contributing/environment/README.md delete mode 100644 docs/contributing/flow/README.md delete mode 100644 docs/contributing/tools/README.md create mode 100644 tests/lint/test_no_readme_in_docs.py diff --git a/README.md b/README.md index 8094a65c03..a6af79bd57 100644 --- a/README.md +++ b/README.md @@ -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). diff --git a/docs/agents/README.md b/docs/agents/README.md deleted file mode 100644 index aee24dcc87..0000000000 --- a/docs/agents/README.md +++ /dev/null @@ -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. diff --git a/docs/agents/action/README.md b/docs/agents/action/README.md deleted file mode 100644 index f579632e1c..0000000000 --- a/docs/agents/action/README.md +++ /dev/null @@ -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. diff --git a/docs/agents/files/README.md b/docs/agents/files/README.md deleted file mode 100644 index b41f1edbff..0000000000 --- a/docs/agents/files/README.md +++ /dev/null @@ -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`. diff --git a/docs/agents/files/role/README.md b/docs/agents/files/role/README.md deleted file mode 100644 index 5ff5ba64c4..0000000000 --- a/docs/agents/files/role/README.md +++ /dev/null @@ -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. diff --git a/docs/agents/meta/README.md b/docs/agents/meta/README.md deleted file mode 100644 index ace810c00e..0000000000 --- a/docs/agents/meta/README.md +++ /dev/null @@ -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. diff --git a/docs/contributing/code/README.md b/docs/contributing/code/README.md deleted file mode 100644 index 492bcfcf34..0000000000 --- a/docs/contributing/code/README.md +++ /dev/null @@ -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. diff --git a/docs/contributing/code/architecture.md b/docs/contributing/code/architecture.md index 05ba017dc7..3f4360e56b 100644 --- a/docs/contributing/code/architecture.md +++ b/docs/contributing/code/architecture.md @@ -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 diff --git a/docs/contributing/code/frameworks/README.md b/docs/contributing/code/frameworks/README.md deleted file mode 100644 index 7608e12e84..0000000000 --- a/docs/contributing/code/frameworks/README.md +++ /dev/null @@ -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. diff --git a/docs/contributing/code/languages/README.md b/docs/contributing/code/languages/README.md deleted file mode 100644 index b9b5f63adb..0000000000 --- a/docs/contributing/code/languages/README.md +++ /dev/null @@ -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. diff --git a/docs/contributing/code/quality.md b/docs/contributing/code/quality.md index 2172160454..3b8c90474b 100644 --- a/docs/contributing/code/quality.md +++ b/docs/contributing/code/quality.md @@ -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). diff --git a/docs/contributing/code/role/README.md b/docs/contributing/code/role/README.md deleted file mode 100644 index 65cd6116e3..0000000000 --- a/docs/contributing/code/role/README.md +++ /dev/null @@ -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. diff --git a/docs/contributing/development/README.md b/docs/contributing/development/README.md deleted file mode 100644 index 63204847b3..0000000000 --- a/docs/contributing/development/README.md +++ /dev/null @@ -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. diff --git a/docs/contributing/development/refactoring.md b/docs/contributing/development/refactoring.md index 395322a990..5326b0156c 100644 --- a/docs/contributing/development/refactoring.md +++ b/docs/contributing/development/refactoring.md @@ -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). diff --git a/docs/contributing/documentation.md b/docs/contributing/documentation.md index aa8d9fd5b4..5aadfdc159 100644 --- a/docs/contributing/documentation.md +++ b/docs/contributing/documentation.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. diff --git a/docs/contributing/environment/README.md b/docs/contributing/environment/README.md deleted file mode 100644 index 42715d7512..0000000000 --- a/docs/contributing/environment/README.md +++ /dev/null @@ -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. diff --git a/docs/contributing/environment/setup.md b/docs/contributing/environment/setup.md index 80bdc4cd16..8336ea951f 100644 --- a/docs/contributing/environment/setup.md +++ b/docs/contributing/environment/setup.md @@ -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). diff --git a/docs/contributing/flow/README.md b/docs/contributing/flow/README.md deleted file mode 100644 index 0e4fb394ae..0000000000 --- a/docs/contributing/flow/README.md +++ /dev/null @@ -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. diff --git a/docs/contributing/flow/review.md b/docs/contributing/flow/review.md index 6bd9ba723c..2d08efd550 100644 --- a/docs/contributing/flow/review.md +++ b/docs/contributing/flow/review.md @@ -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: diff --git a/docs/contributing/tools/README.md b/docs/contributing/tools/README.md deleted file mode 100644 index d0b18d39b4..0000000000 --- a/docs/contributing/tools/README.md +++ /dev/null @@ -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. diff --git a/docs/contributing/tools/docker.md b/docs/contributing/tools/docker.md index 748026f54d..cffac3d55b 100644 --- a/docs/contributing/tools/docker.md +++ b/docs/contributing/tools/docker.md @@ -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 diff --git a/docs/contributing/tools/makefile.md b/docs/contributing/tools/makefile.md index acbdcde7d1..9337176df2 100644 --- a/docs/contributing/tools/makefile.md +++ b/docs/contributing/tools/makefile.md @@ -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). diff --git a/index.rst b/index.rst index a6221f3e41..71a6f6b076 100644 --- a/index.rst +++ b/index.rst @@ -1,4 +1,14 @@ About =============================== -.. markdown-include:: ./README.md \ No newline at end of file +.. markdown-include:: ./README.md + +Documentation +------------- + +The following pages cover contribution guidelines, development workflows, agent instructions, and security references. + +.. toctree:: + :glob: + + docs/** diff --git a/tests/lint/test_no_readme_in_docs.py b/tests/lint/test_no_readme_in_docs.py new file mode 100644 index 0000000000..4088728d24 --- /dev/null +++ b/tests/lint/test_no_readme_in_docs.py @@ -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()