Merge pull request #48 from PyNumLab/website

prepare for website

Author: saidctb

.github/workflows/docs.yml

@@ -0,0 +1,81 @@
+name: Documentation
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - ".github/workflows/docs.yml"
+      - "README.md"
+      - "docs/**"
+      - "mkdocs.yml"
+      - "pyproject.toml"
+      - "tests/docs/**"
+      - "tools/mkdocs_publication.py"
+  pull_request:
+    paths:
+      - ".github/workflows/docs.yml"
+      - "README.md"
+      - "docs/**"
+      - "mkdocs.yml"
+      - "pyproject.toml"
+      - "tests/docs/**"
+      - "tools/mkdocs_publication.py"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pages: write
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+          cache-dependency-path: pyproject.toml
+
+      - name: Install documentation dependencies
+        run: python -m pip install -e ".[docs,qa]"
+
+      - name: Run documentation tests
+        run: python -m pytest -q tests/docs
+
+      - name: Build reviewed documentation
+        run: python -m mkdocs build --strict
+
+      - name: Configure GitHub Pages
+        if: github.ref == 'refs/heads/main' && github.event_name != 'pull_request'
+        uses: actions/configure-pages@v5
+
+      - name: Upload GitHub Pages artifact
+        if: github.ref == 'refs/heads/main' && github.event_name != 'pull_request'
+        uses: actions/upload-pages-artifact@v4
+        with:
+          path: site
+
+  deploy:
+    if: github.ref == 'refs/heads/main' && github.event_name != 'pull_request'
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    permissions:
+      pages: write
+      id-token: write
+    steps:
+      - name: Deploy GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -10,6 +10,7 @@ mutants/
 .ruff_cache/
 .benchmarks/
 htmlcov/
+site/
 
 *.pyc
 *.pyo

AGENTS.md

@@ -17,6 +17,12 @@ When updating tests, remove obsolete tests that only assert removed/old implemen
 
 Before `x2py/semantics/ir2ast.py` runs, the post-IR policy stage must have completed every semantic decision needed by wrapper generation, including object kind, ownership, transfer, destruction, mutability/writeback, nullability, output projection, release responsibility, contract-value storage mode (`stack`, `heap`, or `alias`), getter behavior, native setter assignment, and Python setter exposure. Bridge and binding generators may only dispatch from those completed decisions into small named implementation methods. They must not infer or override semantic policy from datatype, `intent`, dotted-variable shape, `is_alias`, or local memory checks, and they must not contain a fallback that silently chooses a different behavior. When such a decision is found in bridge or binding code, remove it there and move it into post-IR policy completion. Backend-local helper temporaries may still be created inside the selected implementation method because they are emitted-code details, not semantic policy.
 
+For behavior changes, first try to express the change in completed semantic
+policy or the shared wrapper plan. Change binding or bridge lowering only when
+the selected plan requires a genuinely new emitted-code mechanism; those
+generators should otherwise keep reusing and dispatching existing planned
+paths.
+
 After every implementation task, the final summary must include a breakdown of
 the stages that actually changed. Relevant stages include parsing, semantic IR
 construction, post-IR policy completion, IR-to-AST/lowering, binding

README.md

@@ -344,7 +344,7 @@ X2PY_C_DOCS_END -->
 
 For diagnostic and inspection commands beyond the main build path, start with
 `python3 -m x2py --help`, then continue to the
-[Fortran wrapper guide](docs/user/guide/fortran-wrapper.md).
+[CLI command reference](docs/user/reference/cli-commands.md).
 
 <!-- X2PY_C_DOCS_START
 The runtime build path accepts one or more ordered Fortran sources. C parsing,
@@ -557,9 +557,8 @@ ownership, callback lifetime, ABI shims, or Python-visible projections.
 - **[Getting Started](docs/user/getting-started/index.md)** — Installation, verification, standalone procedures, modules, and rebuild workflow
 - **[User Guide](docs/user/guide/index.md)** — Detailed guidance on data types, functions, subroutines, modules, arrays, derived types, callbacks, ownership, runtime behavior, and packaging
 <!--
-- **[Tutorials](docs/user/tutorials/)** — Step-by-step walkthroughs
-- **[Examples Cookbook](docs/user/examples/verified-cookbook.md)** — Ready-to-use Fortran wrapper patterns and recipes
-- **[CLI Reference](docs/user/reference/cli.md)** — Complete command-line documentation
+- **[Tutorials](docs/user/tutorials/index.md)** — Step-by-step walkthroughs
+- **[CLI Reference](docs/user/reference/cli-commands.md)** — Complete command-line documentation
 - **[Language Support](docs/user/language-support/index.md)** — What is supported, partially supported, or planned
 - **[FAQ](docs/user/faq/index.md)** — Concise answers to common questions
 - **[Troubleshooting](docs/user/troubleshooting/index.md)** — Solutions for installation, compiler, build, runtime, and platform issues

docs/developer/adding-a-code-generation-backend.md

@@ -4,6 +4,7 @@ audience: developers, contributors
 prerequisites: code generation design, internal architecture
 related: adding-a-feature.md, build-system.md
 status: planned-documentation
+publication: draft
 ---
 
 # Adding A New Code Generation Backend

docs/developer/adding-a-feature.md

@@ -4,6 +4,7 @@ audience: developers, contributors
 prerequisites: testing strategy, documentation architecture
 related: adding-a-fortran-construct.md, coding-standards.md
 status: planned-documentation
+publication: draft
 ---
 
 # Adding A New Feature

docs/developer/adding-a-fortran-construct.md

@@ -4,6 +4,7 @@ audience: developers, contributors
 prerequisites: parser architecture, semantic analysis
 related: adding-a-feature.md, fortran-parser-reference.md
 status: planned-documentation
+publication: draft
 ---
 
 # Adding A New Fortran Construct

docs/developer/build-system.md

@@ -4,6 +4,7 @@ audience: developers, contributors
 prerequisites: repository structure
 related: testing-strategy.md, ../user/reference/configuration-files.md
 status: planned-documentation
+publication: draft
 ---
 
 # Build System

docs/developer/c-parser-reference.md

@@ -5,6 +5,7 @@ audience: developers
 prerequisites: repository structure, parser architecture
 related: adding-a-feature.md, repository-structure.md
 status: maintained
+publication: draft
 ---
 
 <!-- X2PY_C_DOCS_START

docs/developer/coding-standards.md

@@ -4,6 +4,7 @@ audience: contributors
 prerequisites: repository structure
 related: testing-strategy.md, quality-assurance.md
 status: planned-documentation
+publication: draft
 ---
 
 # Coding Standards