From 2b3362a927bd5f6de45fc65213db70883df80061 Mon Sep 17 00:00:00 2001 From: ignis Date: Wed, 3 Jun 2026 12:00:43 +0000 Subject: [PATCH] Archive legacy pycompact.py python bindings and update documentation with historical context --- build_docs.py | 21 +++++++++++++++++---- code/{ => archive}/pycompact/compact_doc.py | 0 code/{ => archive}/pycompact/pycompact.py | 0 docs/archive/pycompact.md | 6 ++++++ docs/index.md | 5 +++-- docs/python/pycompact.md | 3 --- ford.md | 2 +- mkdocs.yml | 5 +++-- 8 files changed, 30 insertions(+), 12 deletions(-) rename code/{ => archive}/pycompact/compact_doc.py (100%) rename code/{ => archive}/pycompact/pycompact.py (100%) create mode 100644 docs/archive/pycompact.md delete mode 100644 docs/python/pycompact.md diff --git a/build_docs.py b/build_docs.py index 131ba05..6cbb286 100644 --- a/build_docs.py +++ b/build_docs.py @@ -67,15 +67,16 @@ graph TD F[post.f90 / Main Driver] -->|Orchestrates calculations| C F -->|Parallelizes domain| G[m_openmpi.f90] F -->|Loads run configuration| H[m_parameters.f90] - I[pycompact.py / Bindings] -->|Wraps CPU calculations| C + I[pycompact.py / Legacy Bindings - Archived] -.->|Transitional| C ``` --- ## Navigation Guide -- **[Python API Reference](python/code_gen.md)**: Automatically parsed API and signatures for the DSL parsers, topological compiler stages, and Python wrappers. +- **[Python API Reference](python/code_gen.md)**: Automatically parsed API and signatures for the DSL parsers, topological compiler stages, and code generation routines. - **[Fortran Core Reference](fortran.md)**: Standard documentation compiled by `FORD` covering tridiagonal compact solvers, math kernels, and MPI bindings. +- **[Archived Python Bindings](archive/pycompact.md)**: Legacy bindings wrapping calculation kernels. *Generated automatically using industry-standard tools: FORD, MkDocs, and Material theme.* """) @@ -109,8 +110,7 @@ The Fortran core elements have been fully documented and compiled using **FORD** # 3. Create Python stubs for mkdocstrings python_modules = [ ("code_gen", "Code Generator (`code_gen.py`)"), - ("post", "Compiler Stages (`post.py`)"), - ("pycompact", "Python Bindings (`pycompact.py`)") + ("post", "Compiler Stages (`post.py`)") ] for mod_name, title in python_modules: stub_path = os.path.join(docs_dir, "python", f"{mod_name}.md") @@ -119,6 +119,19 @@ The Fortran core elements have been fully documented and compiled using **FORD** f.write(f"""# {title} ::: {mod_name} +""") + + # Create Archived Python Bindings stub + os.makedirs(os.path.join(docs_dir, "archive"), exist_ok=True) + archive_stub_path = os.path.join(docs_dir, "archive", "pycompact.md") + print(f"Creating Archived Python Bindings stub: {archive_stub_path}") + with open(archive_stub_path, 'w', encoding='utf-8') as f: + f.write("""# Archived Python Bindings (`pycompact.py`) + +!!! warning "Archived/Legacy Component" + **Historical Note**: Originally, researchers manually wrote post-processing Fortran codes. To reduce this maintenance overhead, python bindings (`pycompact.py`) were introduced as a transitional wrapper. However, since the bindings did not significantly improve ease of use, we subsequently defined a custom DSL (Domain Specific Language) for describing post-processing operations and developed a compiler (`code_gen.py` & `post.py`) to generate highly optimized Fortran codes. As a result, the python bindings are now archived. + +::: pycompact """) # 4. Environment validation diff --git a/code/pycompact/compact_doc.py b/code/archive/pycompact/compact_doc.py similarity index 100% rename from code/pycompact/compact_doc.py rename to code/archive/pycompact/compact_doc.py diff --git a/code/pycompact/pycompact.py b/code/archive/pycompact/pycompact.py similarity index 100% rename from code/pycompact/pycompact.py rename to code/archive/pycompact/pycompact.py diff --git a/docs/archive/pycompact.md b/docs/archive/pycompact.md new file mode 100644 index 0000000..ff93ecb --- /dev/null +++ b/docs/archive/pycompact.md @@ -0,0 +1,6 @@ +# Archived Python Bindings (`pycompact.py`) + +!!! warning "Archived/Legacy Component" + **Historical Note**: Originally, researchers manually wrote post-processing Fortran codes. To reduce this maintenance overhead, python bindings (`pycompact.py`) were introduced as a transitional wrapper. However, since the bindings did not significantly improve ease of use, we subsequently defined a custom DSL (Domain Specific Language) for describing post-processing operations and developed a compiler (`code_gen.py` & `post.py`) to generate highly optimized Fortran codes. As a result, the python bindings are now archived. + +::: pycompact diff --git a/docs/index.md b/docs/index.md index 25dd59a..bed4a0b 100644 --- a/docs/index.md +++ b/docs/index.md @@ -17,14 +17,15 @@ graph TD F[post.f90 / Main Driver] -->|Orchestrates calculations| C F -->|Parallelizes domain| G[m_openmpi.f90] F -->|Loads run configuration| H[m_parameters.f90] - I[pycompact.py / Bindings] -->|Wraps CPU calculations| C + I[pycompact.py / Legacy Bindings - Archived] -.->|Transitional| C ``` --- ## Navigation Guide -- **[Python API Reference](python/code_gen.md)**: Automatically parsed API and signatures for the DSL parsers, topological compiler stages, and Python wrappers. +- **[Python API Reference](python/code_gen.md)**: Automatically parsed API and signatures for the DSL parsers, topological compiler stages, and code generation routines. - **[Fortran Core Reference](fortran.md)**: Standard documentation compiled by `FORD` covering tridiagonal compact solvers, math kernels, and MPI bindings. +- **[Archived Python Bindings](archive/pycompact.md)**: Legacy bindings wrapping calculation kernels. *Generated automatically using industry-standard tools: FORD, MkDocs, and Material theme.* diff --git a/docs/python/pycompact.md b/docs/python/pycompact.md deleted file mode 100644 index e7a154d..0000000 --- a/docs/python/pycompact.md +++ /dev/null @@ -1,3 +0,0 @@ -# Python Bindings (`pycompact.py`) - -::: pycompact diff --git a/ford.md b/ford.md index f4ee1fa..e9de786 100644 --- a/ford.md +++ b/ford.md @@ -5,7 +5,7 @@ author: Google DeepMind Team & Ignis version: 1.0.0 src_dir: ./code output_dir: ./docs/fortran_api -exclude: **/pycompact/** +exclude: **/archive/** preprocess: true display: public --- diff --git a/mkdocs.yml b/mkdocs.yml index c89b692..28ca232 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -28,7 +28,7 @@ plugins: default_handler: python handlers: python: - paths: [code, code/code_gen, code/pycompact] + paths: [code, code/code_gen, code/archive/pycompact] options: docstring_style: google show_source: true @@ -40,7 +40,8 @@ nav: - Python API Reference: - Code Generator: python/code_gen.md - Compiler Stages: python/post.md - - Python Bindings: python/pycompact.md + - Archived Components: + - Python Bindings: archive/pycompact.md - Fortran Core Reference: - Modules & Procedures: fortran.md