|
35 | 35 | html_static_path = ["_assets"] |
36 | 36 | html_css_files = ["custom.css"] |
37 | 37 |
|
38 | | -# :need:`{title}` is used in the needs templates to display the title of the need |
39 | | -needs_role_need_template = "{title}" |
| 38 | +# Training portals are pre-generated into trainings/_portals/ by build.py. |
| 39 | +# This copies the subdirectory tree (e.g. requirements_engineering/) verbatim |
| 40 | +# into the Sphinx HTML output root so portals are served alongside the docs. |
| 41 | +html_extra_path = ["trainings/_portals"] |
| 42 | + |
| 43 | +# exclude pattern are not supported when calling sphinx-build from other repositories, |
| 44 | +# so we do not use them here. Instead, the exclusion of training source files |
| 45 | +# and generated portal files is handled in the Sphinx build hook below. |
| 46 | +# Exclude training source files and generated portal files from Sphinx processing. |
| 47 | +# - trainings/*/source/** : Markdown source files for the training portals |
| 48 | +# - trainings/trainings_templates/** : Template files, not Sphinx documents |
| 49 | +# - trainings/_portals/** : Generated portal HTML (served via html_extra_path) |
| 50 | +#exclude_patterns = [ |
| 51 | +# "trainings/*/source/**", |
| 52 | +# "trainings/trainings_templates/**", |
| 53 | +# "trainings/_portals/**", |
| 54 | +#] |
| 55 | + |
| 56 | +# :need:`{{ title }}` is used in the needs templates to display the title of the need |
| 57 | +needs_role_need_template = "{{ title }}" |
| 58 | + |
| 59 | + |
| 60 | +# --------------------------------------------------------------------------- |
| 61 | +# Training portal build hook |
| 62 | +# |
| 63 | +# Automatically regenerates all training portals before Sphinx processes the |
| 64 | +# documentation. build.py requires the 'markdown' package which is NOT part |
| 65 | +# of the docs-as-code Sphinx environment, so it is run via the dedicated |
| 66 | +# .venv virtual environment. If that venv is absent it is created |
| 67 | +# and the required packages are installed automatically. |
| 68 | +# --------------------------------------------------------------------------- |
| 69 | + |
| 70 | +def _build_training_portals(app): |
| 71 | + """Sphinx builder-inited event handler: regenerate all training portals.""" |
| 72 | + import os, subprocess, sys |
| 73 | + from pathlib import Path |
| 74 | + |
| 75 | + conf_dir = Path(app.confdir) # …/process/ |
| 76 | + repo_root = conf_dir.parent # …/process_description/ |
| 77 | + venv_dir = repo_root / ".venv" |
| 78 | + venv_python = venv_dir / "bin" / "python" |
| 79 | + |
| 80 | + # Locate all training source build scripts |
| 81 | + build_scripts = sorted(conf_dir.glob( |
| 82 | + "trainings/*/source/build.py" |
| 83 | + )) |
| 84 | + if not build_scripts: |
| 85 | + return |
| 86 | + |
| 87 | + # Ensure the venv exists with the required packages |
| 88 | + if not venv_python.exists(): |
| 89 | + reqs_file = build_scripts[0].parent / "requirements.txt" |
| 90 | + try: |
| 91 | + subprocess.run( |
| 92 | + [sys.executable, "-m", "venv", str(venv_dir)], |
| 93 | + check=True, capture_output=True, |
| 94 | + ) |
| 95 | + if reqs_file.exists(): |
| 96 | + subprocess.run( |
| 97 | + [str(venv_python), "-m", "pip", "install", "-q", |
| 98 | + "-r", str(reqs_file)], |
| 99 | + check=True, capture_output=True, |
| 100 | + ) |
| 101 | + except Exception as exc: |
| 102 | + import warnings |
| 103 | + warnings.warn( |
| 104 | + f"[trainings] Could not create .venv_training: {exc}\n" |
| 105 | + " Training portals will not be regenerated. " |
| 106 | + "Run source/build.py manually.", |
| 107 | + stacklevel=1, |
| 108 | + ) |
| 109 | + return |
| 110 | + |
| 111 | + # Run each build script |
| 112 | + for script in build_scripts: |
| 113 | + try: |
| 114 | + subprocess.run( |
| 115 | + [str(venv_python), str(script)], |
| 116 | + cwd=str(script.parent), |
| 117 | + check=True, capture_output=True, |
| 118 | + ) |
| 119 | + print(f"[trainings] Built portal: {script.parent.parent.name}") |
| 120 | + except subprocess.CalledProcessError as exc: |
| 121 | + import warnings |
| 122 | + warnings.warn( |
| 123 | + f"[trainings] Portal build failed for {script.parent.parent.name}:\n" |
| 124 | + f" {exc.stderr.decode(errors='replace').strip()}", |
| 125 | + stacklevel=1, |
| 126 | + ) |
| 127 | + |
| 128 | + |
| 129 | +def setup(app): |
| 130 | + app.connect("builder-inited", _build_training_portals) |
0 commit comments