Merge pull request #3 from GapIntelligence/codex/improve-repository

Replace dummy module with MkDocs build test

Author: KristopherKubicki

README.md

@@ -4,3 +4,17 @@
 [![codecov](https://codecov.io/gh/GapIntelligence/.github/graph/badge.svg?token=GQXX40CMBF)](https://codecov.io/gh/GapIntelligence/.github)
 
 This repository contains configuration files and documentation used by OpenBrand.
+
+## Documentation
+
+For an overview of the organization, visit the [profile README](profile/README.md).
+The MkDocs site is built from the files in the [`docs/`](docs/) directory.
+
+## Development
+
+This repository uses [MkDocs](https://www.mkdocs.org/) for documentation.
+Run the test suite (which also builds the site) with:
+
+```bash
+python -m pytest -q
+```

docs/index.md

@@ -0,0 +1,7 @@
+# OpenBrand Documentation
+
+This site contains documentation about the OpenBrand organization.
+
+For repository details, see the [main README](../README.md).
+
+Learn more about our organization on the [profile page](profile.md).

docs/profile.md

@@ -0,0 +1,3 @@
+# OpenBrand Profile
+
+This page mirrors the information in [profile/README.md](../profile/README.md).

dummy.py

@@ -0,0 +1,5 @@
+site_name: OpenBrand Docs
+nav:
+  - Home: index.md
+  - Profile: profile.md
+docs_dir: docs

mkdocs.yml

@@ -59,4 +59,6 @@ To get started with development, please ensure you have access to the necessary
 
 ---
 
+For repository configuration details, see the [main README](../README.md).
+
 Thank you for contributing to OpenBrand's continued success!

profile/README.md

@@ -1,2 +1,3 @@
 pytest
 pytest-cov
+mkdocs

requirements.txt

@@ -0,0 +1,15 @@
+import subprocess
+from pathlib import Path
+
+
+def test_mkdocs_build(tmp_path: Path) -> None:
+    """Ensure the mkdocs site builds successfully."""
+    site_dir = tmp_path / "site"
+    result = subprocess.run([
+        "mkdocs",
+        "build",
+        "--site-dir",
+        str(site_dir),
+    ], capture_output=True, text=True)
+    assert result.returncode == 0, result.stderr
+    assert site_dir.exists()