43499f58e3
All checks were successful
Deploy Documentation / build-and-deploy (push) Successful in 3m17s
118 lines
4.2 KiB
Python
118 lines
4.2 KiB
Python
#!/usr/bin/env python3
|
|
import os
|
|
import shutil
|
|
import subprocess
|
|
import sys
|
|
|
|
def check_command_installed(cmd):
|
|
"""Checks if a command-line tool is installed in the current environment."""
|
|
return shutil.which(cmd) is not None
|
|
|
|
def run_process(args, description):
|
|
"""Runs a subprocess with clean console updates."""
|
|
print(f"\n[Running] {description}...")
|
|
try:
|
|
res = subprocess.run(args, check=True, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
|
|
print(f"[Success] {description} completed successfully!")
|
|
if res.stdout.strip():
|
|
print(res.stdout.strip())
|
|
return True
|
|
except subprocess.CalledProcessError as e:
|
|
print(f"[Error] {description} FAILED with exit code {e.returncode}!")
|
|
if e.stdout:
|
|
print("--- STDOUT ---")
|
|
print(e.stdout.strip())
|
|
if e.stderr:
|
|
print("--- STDERR ---")
|
|
print(e.stderr.strip())
|
|
return False
|
|
except Exception as e:
|
|
print(f"[Error] Failed to execute process: {e}")
|
|
return False
|
|
|
|
def build_orchestrator():
|
|
workspace_dir = os.path.dirname(os.path.abspath(__file__))
|
|
docs_dir = os.path.join(workspace_dir, "docs")
|
|
site_dir = os.path.join(workspace_dir, "site")
|
|
|
|
# Clean old docs and site
|
|
if os.path.exists(docs_dir):
|
|
shutil.rmtree(docs_dir)
|
|
os.makedirs(docs_dir, exist_ok=True)
|
|
os.makedirs(os.path.join(docs_dir, "python"), exist_ok=True)
|
|
|
|
if os.path.exists(site_dir):
|
|
shutil.rmtree(site_dir)
|
|
|
|
# 1. Create landing index.md
|
|
index_path = os.path.join(docs_dir, "index.md")
|
|
print(f"Creating landing index: {index_path}")
|
|
with open(index_path, 'w', encoding='utf-8') as f:
|
|
f.write("""# Coke Oven Maintenance Plan Reference Manual
|
|
|
|
Welcome to the automated documentation suite for the coke oven maintenance plan project! This manual provides comprehensive technical reference for simulating coke oven processes, thermal dynamics, and battery operations.
|
|
|
|
---
|
|
|
|
## Architecture Overview
|
|
|
|
This project simulates the thermal response of a coke oven battery including combustion chambers, refractory brick walls, and oven charges. Below is the primary object-oriented component interaction:
|
|
|
|
```mermaid
|
|
graph TD
|
|
Battery[Battery] -->|Manages| CombustionChamber[CombustionChamber]
|
|
Battery -->|Manages| RefractoryWall[RefractoryWall]
|
|
Battery -->|Manages| OvenChamber[OvenChamber]
|
|
OvenChamber -->|Holds| CokeCharge[CokeCharge]
|
|
RefractoryWall -->|Uses| TInternal[TInternal]
|
|
RefractoryWall -->|Uses| CokeOvenBrickHeatEqn[CokeOvenBrickHeatEqn]
|
|
```
|
|
|
|
---
|
|
|
|
## Navigation Guide
|
|
|
|
- **[Python API Reference](python/battery.md)**: Automatically parsed API, signatures, and detailed documentation for the `Battery.py` classes and helper subroutines.
|
|
|
|
*Generated automatically using industry-standard tools: MkDocs, mkdocstrings, and Material theme.*
|
|
""")
|
|
|
|
# 2. Create Python stubs for mkdocstrings
|
|
stub_path = os.path.join(docs_dir, "python", "battery.md")
|
|
print(f"Creating Python stub: {stub_path}")
|
|
with open(stub_path, 'w', encoding='utf-8') as f:
|
|
f.write("""# Battery API Reference
|
|
|
|
::: Battery
|
|
""")
|
|
|
|
# 3. Environment validation
|
|
if not check_command_installed("mkdocs"):
|
|
print("\n" + "="*80)
|
|
print(" [Warning] Missing Required Documentation Tools!")
|
|
print("="*80)
|
|
print("To compile the complete manual, please install the requirements:")
|
|
print(" pip install -r requirements-docs.txt")
|
|
print("Note: If running in a virtualenv, make sure it is activated.")
|
|
print("="*80 + "\n")
|
|
return False
|
|
|
|
# 4. Compile Python API and build MkDocs site
|
|
mkdocs_success = run_process(["mkdocs", "build"], "MkDocs Website Compiler")
|
|
if mkdocs_success:
|
|
print("\n" + "="*80)
|
|
print(" 🎉 Documentation manual built successfully!")
|
|
print("="*80)
|
|
print(f"Output directory: {site_dir}")
|
|
print("To view or serve the website locally, run:")
|
|
print(" mkdocs serve")
|
|
print("="*80)
|
|
else:
|
|
print("\n[Error] MkDocs website compilation FAILED!")
|
|
return False
|
|
|
|
return True
|
|
|
|
if __name__ == "__main__":
|
|
success = build_orchestrator()
|
|
sys.exit(0 if success else 1)
|