dgo-atlas 0.5.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (98) hide show
  1. dgo_atlas-0.5.0/.claude/launch.json +12 -0
  2. dgo_atlas-0.5.0/.github/workflows/release.yml +83 -0
  3. dgo_atlas-0.5.0/.gitignore +228 -0
  4. dgo_atlas-0.5.0/.vscode/settings.json +9 -0
  5. dgo_atlas-0.5.0/CLAUDE.md +162 -0
  6. dgo_atlas-0.5.0/LICENSE +21 -0
  7. dgo_atlas-0.5.0/PKG-INFO +99 -0
  8. dgo_atlas-0.5.0/README.md +81 -0
  9. dgo_atlas-0.5.0/dgo-atlas.example.yaml +334 -0
  10. dgo_atlas-0.5.0/docs/reference.md +244 -0
  11. dgo_atlas-0.5.0/pyproject.toml +36 -0
  12. dgo_atlas-0.5.0/src/dgo_atlas/__init__.py +9 -0
  13. dgo_atlas-0.5.0/src/dgo_atlas/build.py +127 -0
  14. dgo_atlas-0.5.0/src/dgo_atlas/cli/__init__.py +66 -0
  15. dgo_atlas-0.5.0/src/dgo_atlas/cli/common.py +37 -0
  16. dgo_atlas-0.5.0/src/dgo_atlas/cli/new.py +44 -0
  17. dgo_atlas-0.5.0/src/dgo_atlas/cli/project.py +71 -0
  18. dgo_atlas-0.5.0/src/dgo_atlas/cli/site.py +26 -0
  19. dgo_atlas-0.5.0/src/dgo_atlas/config.py +140 -0
  20. dgo_atlas-0.5.0/src/dgo_atlas/console.py +43 -0
  21. dgo_atlas-0.5.0/src/dgo_atlas/content.py +173 -0
  22. dgo_atlas-0.5.0/src/dgo_atlas/convert.py +39 -0
  23. dgo_atlas-0.5.0/src/dgo_atlas/derive.py +477 -0
  24. dgo_atlas-0.5.0/src/dgo_atlas/dgo.py +345 -0
  25. dgo_atlas-0.5.0/src/dgo_atlas/editor.py +33 -0
  26. dgo_atlas-0.5.0/src/dgo_atlas/generate.py +213 -0
  27. dgo_atlas-0.5.0/src/dgo_atlas/linkcheck.py +86 -0
  28. dgo_atlas-0.5.0/src/dgo_atlas/loader.py +87 -0
  29. dgo_atlas-0.5.0/src/dgo_atlas/models/__init__.py +0 -0
  30. dgo_atlas-0.5.0/src/dgo_atlas/models/config.py +198 -0
  31. dgo_atlas-0.5.0/src/dgo_atlas/models/viewmodel.py +458 -0
  32. dgo_atlas-0.5.0/src/dgo_atlas/render.py +464 -0
  33. dgo_atlas-0.5.0/src/dgo_atlas/resources.py +20 -0
  34. dgo_atlas-0.5.0/src/dgo_atlas/scaffold/README.md +131 -0
  35. dgo_atlas-0.5.0/src/dgo_atlas/scaffold/content/how-to-contribute.md +23 -0
  36. dgo_atlas-0.5.0/src/dgo_atlas/scaffold/content/index.md +10 -0
  37. dgo_atlas-0.5.0/src/dgo_atlas/scaffold/dgo-atlas.yaml +63 -0
  38. dgo_atlas-0.5.0/src/dgo_atlas/scaffold/dot-github/workflows/site.yml +59 -0
  39. dgo_atlas-0.5.0/src/dgo_atlas/scaffold/dot-gitignore +4 -0
  40. dgo_atlas-0.5.0/src/dgo_atlas/scaffold/dot-vscode/extensions.json +3 -0
  41. dgo_atlas-0.5.0/src/dgo_atlas/scaffold/dot-vscode/settings.json +7 -0
  42. dgo_atlas-0.5.0/src/dgo_atlas/scaffold/governance/glossary.yaml +21 -0
  43. dgo_atlas-0.5.0/src/dgo_atlas/scaffold/governance/organization.yaml +43 -0
  44. dgo_atlas-0.5.0/src/dgo_atlas/scaffold/governance/terms/clinical-study.yaml +20 -0
  45. dgo_atlas-0.5.0/src/dgo_atlas/scaffold/governance/terms/clinical-trial.yaml +42 -0
  46. dgo_atlas-0.5.0/src/dgo_atlas/scaffold/pyproject.toml +12 -0
  47. dgo_atlas-0.5.0/src/dgo_atlas/scaffold.py +43 -0
  48. dgo_atlas-0.5.0/src/dgo_atlas/schema/config.schema.json +537 -0
  49. dgo_atlas-0.5.0/src/dgo_atlas/schema/config.yaml +175 -0
  50. dgo_atlas-0.5.0/src/dgo_atlas/schema/template.yaml +134 -0
  51. dgo_atlas-0.5.0/src/dgo_atlas/schema/viewmodel.yaml +336 -0
  52. dgo_atlas-0.5.0/src/dgo_atlas/semantic.py +109 -0
  53. dgo_atlas-0.5.0/src/dgo_atlas/static/site.css +1143 -0
  54. dgo_atlas-0.5.0/src/dgo_atlas/static/site.js +440 -0
  55. dgo_atlas-0.5.0/src/dgo_atlas/templates/_brand.html.j2 +12 -0
  56. dgo_atlas-0.5.0/src/dgo_atlas/templates/_brand_link.html.j2 +10 -0
  57. dgo_atlas-0.5.0/src/dgo_atlas/templates/_footer.html.j2 +11 -0
  58. dgo_atlas-0.5.0/src/dgo_atlas/templates/_head.html.j2 +13 -0
  59. dgo_atlas-0.5.0/src/dgo_atlas/templates/_macros.html.j2 +61 -0
  60. dgo_atlas-0.5.0/src/dgo_atlas/templates/_page_head.html.j2 +9 -0
  61. dgo_atlas-0.5.0/src/dgo_atlas/templates/_responsibilities.html.j2 +25 -0
  62. dgo_atlas-0.5.0/src/dgo_atlas/templates/agent.html.j2 +61 -0
  63. dgo_atlas-0.5.0/src/dgo_atlas/templates/area.html.j2 +31 -0
  64. dgo_atlas-0.5.0/src/dgo_atlas/templates/base.html.j2 +118 -0
  65. dgo_atlas-0.5.0/src/dgo_atlas/templates/council.html.j2 +78 -0
  66. dgo_atlas-0.5.0/src/dgo_atlas/templates/directory.html.j2 +26 -0
  67. dgo_atlas-0.5.0/src/dgo_atlas/templates/domain.html.j2 +26 -0
  68. dgo_atlas-0.5.0/src/dgo_atlas/templates/glossary.html.j2 +26 -0
  69. dgo_atlas-0.5.0/src/dgo_atlas/templates/governance.html.j2 +49 -0
  70. dgo_atlas-0.5.0/src/dgo_atlas/templates/how_to_read.html.j2 +74 -0
  71. dgo_atlas-0.5.0/src/dgo_atlas/templates/hub.html.j2 +89 -0
  72. dgo_atlas-0.5.0/src/dgo_atlas/templates/not_found.html.j2 +38 -0
  73. dgo_atlas-0.5.0/src/dgo_atlas/templates/page.html.j2 +37 -0
  74. dgo_atlas-0.5.0/src/dgo_atlas/templates/term.html.j2 +161 -0
  75. dgo_atlas-0.5.0/src/dgo_atlas/templates/terms_index.html.j2 +54 -0
  76. dgo_atlas-0.5.0/src/dgo_atlas/text.py +89 -0
  77. dgo_atlas-0.5.0/src/dgo_atlas/text.yaml +288 -0
  78. dgo_atlas-0.5.0/src/dgo_atlas/validate.py +416 -0
  79. dgo_atlas-0.5.0/tests/__init__.py +0 -0
  80. dgo_atlas-0.5.0/tests/conftest.py +60 -0
  81. dgo_atlas-0.5.0/tests/fixtures/variant/content/governance.md +11 -0
  82. dgo_atlas-0.5.0/tests/fixtures/variant/content/how-to-contribute.md +23 -0
  83. dgo_atlas-0.5.0/tests/fixtures/variant/content/index.md +10 -0
  84. dgo_atlas-0.5.0/tests/fixtures/variant/dgo-atlas.yaml +56 -0
  85. dgo_atlas-0.5.0/tests/fixtures/variant/governance/changes.yaml +27 -0
  86. dgo_atlas-0.5.0/tests/fixtures/variant/governance/clinical-investigation-creation.yaml +18 -0
  87. dgo_atlas-0.5.0/tests/fixtures/variant/governance/governance.yaml +159 -0
  88. dgo_atlas-0.5.0/tests/fixtures/variant/governance/sponsored-programs.yaml +77 -0
  89. dgo_atlas-0.5.0/tests/test_build.py +111 -0
  90. dgo_atlas-0.5.0/tests/test_cli.py +93 -0
  91. dgo_atlas-0.5.0/tests/test_derive.py +245 -0
  92. dgo_atlas-0.5.0/tests/test_dgo.py +97 -0
  93. dgo_atlas-0.5.0/tests/test_generated.py +8 -0
  94. dgo_atlas-0.5.0/tests/test_scaffold.py +80 -0
  95. dgo_atlas-0.5.0/tests/test_semantic.py +73 -0
  96. dgo_atlas-0.5.0/tests/test_text.py +104 -0
  97. dgo_atlas-0.5.0/tests/test_validate.py +172 -0
  98. dgo_atlas-0.5.0/uv.lock +2401 -0
@@ -0,0 +1,12 @@
1
+ {
2
+ "version": "0.0.1",
3
+ "configurations": [
4
+ {
5
+ "name": "preview",
6
+ "runtimeExecutable": "sh",
7
+ "runtimeArgs": ["-c", "uv run dgo-atlas build --project tests/fixtures/variant --out .preview && exec python3 -m http.server \"${PORT:-8765}\" --directory .preview"],
8
+ "port": 8765,
9
+ "autoPort": true
10
+ }
11
+ ]
12
+ }
@@ -0,0 +1,83 @@
1
+ # Publish dgo-atlas to PyPI when a GitHub release is published. To rerun a
2
+ # release by hand, start this workflow and choose the release's tag (not a
3
+ # branch) under "Use workflow from".
4
+ #
5
+ # The release tag is the bare version (0.5.0, no "v") and is the only place
6
+ # the version needs to be set. Before testing and building, this workflow
7
+ # writes it into `version` in pyproject.toml, re-locks uv.lock to match and
8
+ # writes it into `__version__`. Those edits exist only in the build; they are
9
+ # not committed back to the repository.
10
+ #
11
+ # PyPI accepts the upload through trusted publishing, so no token is stored.
12
+ # One-time setup on PyPI: add a trusted publisher for project `dgo-atlas`,
13
+ # owner `james-geiger`, repository `dgo-atlas`, workflow `release.yml`,
14
+ # environment `pypi`.
15
+
16
+ name: Release
17
+
18
+ on:
19
+ release:
20
+ types: [published]
21
+ workflow_dispatch:
22
+
23
+ permissions:
24
+ contents: read
25
+
26
+ jobs:
27
+ build:
28
+ runs-on: ubuntu-latest
29
+ steps:
30
+ - name: Check this run is for a tag
31
+ if: github.ref_type != 'tag'
32
+ run: |
33
+ echo "::error::$GITHUB_REF_NAME is a branch; run this workflow on a release tag"
34
+ exit 1
35
+
36
+ - uses: actions/checkout@v5
37
+
38
+ - uses: astral-sh/setup-uv@v6
39
+
40
+ - name: Set the version from the tag
41
+ # `uv version` rejects a tag that isn't a version, writes pyproject.toml
42
+ # and re-locks uv.lock.
43
+ run: |
44
+ uv version "$GITHUB_REF_NAME" --no-sync
45
+ sed -i "s/^__version__ = .*/__version__ = \"$GITHUB_REF_NAME\"/" src/dgo_atlas/__init__.py
46
+ git diff
47
+
48
+ - name: Test
49
+ # The tests import DGO from its release URL, so they need network.
50
+ run: uv run --locked pytest
51
+
52
+ - name: Build
53
+ run: uv build
54
+
55
+ - name: Check the built package reports the tag's version
56
+ run: |
57
+ reported="$(uvx --isolated --from ./dist/*.whl dgo-atlas --version | head -n 1)"
58
+ if [ "$reported" != "dgo-atlas $GITHUB_REF_NAME" ]; then
59
+ echo "::error file=src/dgo_atlas/__init__.py::the built package reports '$reported' but the tag is $GITHUB_REF_NAME"
60
+ exit 1
61
+ fi
62
+
63
+ - uses: actions/upload-artifact@v4
64
+ with:
65
+ name: dist
66
+ path: dist/
67
+ if-no-files-found: error
68
+
69
+ publish:
70
+ needs: build
71
+ runs-on: ubuntu-latest
72
+ environment:
73
+ name: pypi
74
+ url: https://pypi.org/p/dgo-atlas
75
+ permissions:
76
+ id-token: write
77
+ steps:
78
+ - uses: actions/download-artifact@v4
79
+ with:
80
+ name: dist
81
+ path: dist/
82
+
83
+ - uses: pypa/gh-action-pypi-publish@release/v1
@@ -0,0 +1,228 @@
1
+ # Byte-compiled / optimized / DLL files
2
+ __pycache__/
3
+ *.py[codz]
4
+ *$py.class
5
+
6
+ # C extensions
7
+ *.so
8
+
9
+ # Distribution / packaging
10
+ .Python
11
+ build/
12
+ develop-eggs/
13
+ dist/
14
+ downloads/
15
+ eggs/
16
+ .eggs/
17
+ lib/
18
+ lib64/
19
+ parts/
20
+ sdist/
21
+ var/
22
+ wheels/
23
+ share/python-wheels/
24
+ *.egg-info/
25
+ .installed.cfg
26
+ *.egg
27
+ MANIFEST
28
+
29
+ # PyInstaller
30
+ # Usually these files are written by a python script from a template
31
+ # before PyInstaller builds the exe, so as to inject date/other infos into it.
32
+ *.manifest
33
+ *.spec
34
+
35
+ # Installer logs
36
+ pip-log.txt
37
+ pip-delete-this-directory.txt
38
+
39
+ # Unit test / coverage reports
40
+ htmlcov/
41
+ .tox/
42
+ .nox/
43
+ .coverage
44
+ .coverage.*
45
+ .cache
46
+ nosetests.xml
47
+ coverage.xml
48
+ *.cover
49
+ *.py.cover
50
+ .hypothesis/
51
+ .pytest_cache/
52
+ cover/
53
+
54
+ # Translations
55
+ *.mo
56
+ *.pot
57
+
58
+ # Django stuff:
59
+ *.log
60
+ local_settings.py
61
+ db.sqlite3
62
+ db.sqlite3-journal
63
+
64
+ # Flask stuff:
65
+ instance/
66
+ .webassets-cache
67
+
68
+ # Scrapy stuff:
69
+ .scrapy
70
+
71
+ # Sphinx documentation
72
+ docs/_build/
73
+
74
+ # PyBuilder
75
+ .pybuilder/
76
+ target/
77
+
78
+ # Jupyter Notebook
79
+ .ipynb_checkpoints
80
+
81
+ # IPython
82
+ profile_default/
83
+ ipython_config.py
84
+
85
+ # pyenv
86
+ # For a library or package, you might want to ignore these files since the code is
87
+ # intended to run in multiple environments; otherwise, check them in:
88
+ # .python-version
89
+
90
+ # pipenv
91
+ # According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
92
+ # However, in case of collaboration, if having platform-specific dependencies or dependencies
93
+ # having no cross-platform support, pipenv may install dependencies that don't work, or not
94
+ # install all needed dependencies.
95
+ # Pipfile.lock
96
+
97
+ # UV
98
+ # Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
99
+ # This is especially recommended for binary packages to ensure reproducibility, and is more
100
+ # commonly ignored for libraries.
101
+ # uv.lock
102
+
103
+ # poetry
104
+ # Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
105
+ # This is especially recommended for binary packages to ensure reproducibility, and is more
106
+ # commonly ignored for libraries.
107
+ # https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
108
+ # poetry.lock
109
+ # poetry.toml
110
+
111
+ # pdm
112
+ # Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
113
+ # pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
114
+ # https://pdm-project.org/en/latest/usage/project/#working-with-version-control
115
+ # pdm.lock
116
+ # pdm.toml
117
+ .pdm-python
118
+ .pdm-build/
119
+
120
+ # pixi
121
+ # Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
122
+ # pixi.lock
123
+ # Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
124
+ # in the .venv directory. It is recommended not to include this directory in version control.
125
+ .pixi
126
+
127
+ # PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
128
+ __pypackages__/
129
+
130
+ # Celery stuff
131
+ celerybeat-schedule
132
+ celerybeat.pid
133
+
134
+ # Redis
135
+ *.rdb
136
+ *.aof
137
+ *.pid
138
+
139
+ # RabbitMQ
140
+ mnesia/
141
+ rabbitmq/
142
+ rabbitmq-data/
143
+
144
+ # ActiveMQ
145
+ activemq-data/
146
+
147
+ # SageMath parsed files
148
+ *.sage.py
149
+
150
+ # Environments
151
+ .env
152
+ .envrc
153
+ .venv
154
+ env/
155
+ venv/
156
+ ENV/
157
+ env.bak/
158
+ venv.bak/
159
+
160
+ # Spyder project settings
161
+ .spyderproject
162
+ .spyproject
163
+
164
+ # Rope project settings
165
+ .ropeproject
166
+
167
+ # mkdocs documentation
168
+ /site
169
+
170
+ # mypy
171
+ .mypy_cache/
172
+ .dmypy.json
173
+ dmypy.json
174
+
175
+ # Pyre type checker
176
+ .pyre/
177
+
178
+ # pytype static type analyzer
179
+ .pytype/
180
+
181
+ # Cython debug symbols
182
+ cython_debug/
183
+
184
+ # PyCharm
185
+ # JetBrains specific template is maintained in a separate JetBrains.gitignore that can
186
+ # be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
187
+ # and can be added to the global gitignore or merged into this file. For a more nuclear
188
+ # option (not recommended) you can uncomment the following to ignore the entire idea folder.
189
+ # .idea/
190
+
191
+ # Abstra
192
+ # Abstra is an AI-powered process automation framework.
193
+ # Ignore directories containing user credentials, local state, and settings.
194
+ # Learn more at https://abstra.io/docs
195
+ .abstra/
196
+
197
+ # Visual Studio Code
198
+ # Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore
199
+ # that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
200
+ # and can be added to the global gitignore or merged into this file. However, if you prefer,
201
+ # you could uncomment the following to ignore the entire vscode folder
202
+ # .vscode/
203
+ # Temporary file for partial code execution
204
+ tempCodeRunnerFile.py
205
+
206
+ # Ruff stuff:
207
+ .ruff_cache/
208
+
209
+ # PyPI configuration file
210
+ .pypirc
211
+
212
+ # Marimo
213
+ marimo/_static/
214
+ marimo/_lsp/
215
+ __marimo__/
216
+
217
+ # Streamlit
218
+ .streamlit/secrets.toml
219
+
220
+ # DGO Atlas
221
+ tests/fixtures/*/site/
222
+ tests/fixtures/*/.dgo-atlas/
223
+
224
+ # local preview build
225
+ /.preview/
226
+
227
+ # VS Code Allotrope ASM extension (zontal.vscode-asm-language-features) cache
228
+ .asm_cache
@@ -0,0 +1,9 @@
1
+ {
2
+ "github.copilot.enable": {
3
+ "*": false,
4
+ "plaintext": false,
5
+ "markdown": false,
6
+ "scminput": false,
7
+ "asm": false
8
+ }
9
+ }
@@ -0,0 +1,162 @@
1
+ # DGO Atlas
2
+
3
+ ## What this repository is
4
+
5
+ DGO Atlas is the middleware between the Data Governance Ontology (DGO) and
6
+ an organization's business glossary. It has two jobs:
7
+
8
+ 1. **Translation.** It takes governance data that people can write and
9
+ produces data that conforms to DGO, and it also works in the other
10
+ direction. Implementers write plain YAML using readable names
11
+ (`type: approved`, `type: owner`). DGO Atlas checks that YAML against a
12
+ LinkML template that imports DGO, then rewrites each readable name as its
13
+ exact DGO class CURIE (`dgo:DGO_00000026`). It resolves references, merges
14
+ the files and derives the facts DGO leaves implicit: a term's state, its
15
+ narrower terms, related terms in both directions, council seats and
16
+ memberships. `dgo-atlas convert` then hands the result to `linkml-convert`,
17
+ so it can be reused as JSON, JSON-LD or RDF individuals of DGO classes.
18
+ 2. **Site generation.** It renders that derived view model as a static
19
+ glossary site, using Jinja templates, a link checker and editor JSON
20
+ Schemas.
21
+
22
+ ```
23
+ DGO (ontology) github.com/james-geiger/dgo the source of truth; imported by URL at a release tag
24
+ ▲
25
+ DGO Atlas (this repo) Python package + Typer CLI template, validator, translation, derivation, site, scaffold, export
26
+ ▲
27
+ implementer repo created by `dgo-atlas init` governance YAML + dgo-atlas.yaml, nothing else
28
+ ```
29
+
30
+ An implementer never writes LinkML, copies DGO files or edits templates. Each
31
+ implementer repo holds only data (`governance/**/*.yaml`), authored Markdown
32
+ (`content/`) and `dgo-atlas.yaml`. If an implementer would have to touch
33
+ anything else to get a result, DGO Atlas is missing a feature.
34
+
35
+ ### The role of DGO
36
+
37
+ - **DGO is upstream and authoritative.** DGO defines the classes, slots,
38
+ ranges and descriptions; DGO Atlas reads them. Look up ontology facts through
39
+ `dgo.py` (`dgo.view()`, `named_types`, `reference_slots`,
40
+ `slot_description`, `REQUIRED_CLASSES`) and never restate them in code,
41
+ templates or copy. The site links each kind to its DGO class IRI and shows
42
+ DGO's own class names and descriptions.
43
+ - **Import it, never vendor it.** Each project sets `dgo_version` in
44
+ `dgo-atlas.yaml`. `dgo.use()` puts that release's `dist/dgo.yaml` from the
45
+ DGO repo in place of the `DGO_IMPORT` placeholder in `schema/template.yaml`.
46
+ The pydantic model and JSON Schema are generated at runtime. Use only
47
+ published release tags, never branches or unpushed commits. `dgo_source`
48
+ overrides the URL for mirrors and offline builds.
49
+ - **Mint nothing in `dgo:`.** DGO Atlas's own schemas use `dgoatlas:`
50
+ (`https://w3id.org/dgo-atlas/`, which is an identifier only and isn't
51
+ registered). The template adds only a `GovernanceRecord` root made of lists.
52
+ Readable type names are a lookup from DGO's own subclass names, not new
53
+ classes or enums.
54
+ - **Report DGO problems upstream.** Don't work around a DGO problem in the
55
+ middleware. If DGO looks wrong or is missing something, say so and suggest
56
+ the upstream change. The user maintains DGO too.
57
+ - **Adding a DGO release:** bump `dgo_version` in `tests/fixtures/variant`,
58
+ run the tests, fix what breaks, then add the release to
59
+ `dgo.TESTED_VERSIONS`. The table "Supporting a new DGO release" in `docs/reference.md` says
60
+ where each kind of expected DGO change lands.
61
+
62
+ ### Implementers
63
+
64
+ `~/Repositories/unmc/data-governance` is the first real implementer. It has
65
+ already migrated and pins a release in its `pyproject.toml`. Releases before
66
+ the rename were called `dgo-site`; moving past them means renaming the pin,
67
+ `dgo-site.yaml`, `.dgo-site/` and the `dgo-site` commands in its CI. Don't break features it relies on, and don't leak its institution-specific
68
+ details (names, colours such as `#AD122A`) into the scaffold, fixtures or
69
+ defaults. DGO Atlas's defaults use a neutral palette.
70
+
71
+ ## How a build flows
72
+
73
+ "How a build works" in `docs/reference.md` has the full details. In brief:
74
+
75
+ | Stage | Module |
76
+ | --- | --- |
77
+ | Load and validate `dgo-atlas.yaml`, then load and check the DGO release | `config.py`, `dgo.py` |
78
+ | Read and merge the data files, and turn readable `type` names into CURIEs | `loader.py`, `dgo.py` |
79
+ | Shape (linkml-validate against the template), references and rules | `validate.py` |
80
+ | Derive the view model (`schema/viewmodel.yaml`, `dgoatlas:`) | `derive.py`, `semantic.py` |
81
+ | Render and link-check | `render.py`, `templates/`, `static/`, `linkcheck.py` |
82
+ | Export via linkml-convert | `convert.py` |
83
+ | Orchestration | `build.py` |
84
+
85
+ Rules to keep:
86
+
87
+ - **Publishing.** A term enters the site only once a term creation is
88
+ recorded for it and that creation hasn't been rejected
89
+ (`derive.unpublished_reason`). A term may go straight to approved. There are
90
+ no "unrecorded" or "rejected" pages; unpublished terms and links to them
91
+ are dropped, and the build prints a note.
92
+ - **State.** The term-state rule is provisional and lives only in
93
+ `derive.term_state`. A term has no status field; its state comes from its
94
+ lifecycle boundaries.
95
+ - **Follow relationships instead of repeating lists.** For example, a council
96
+ page lists the subject areas that hold terms it governs, not every term
97
+ again.
98
+ - **Semantic types** are shown by what the referenced class calls itself
99
+ (OLS, then the IRI dereferenced as RDF). Fall back to the IRI and a build
100
+ note; never make up a label.
101
+ - **Export stays thin.** `convert` passes through to `linkml-convert`. It
102
+ fills in only the input, `-s`, `-C` and `-P`, and forwards everything else
103
+ unchanged. Don't reimplement serialization.
104
+ - **Prefer LinkML's own tooling** (linkml-validate, linkml-convert, gen-doc,
105
+ the pydantic generator) to bespoke code. There is no model-reference page
106
+ in this version; if it comes back, use `gen-doc -f html` with templates.
107
+
108
+ ## Configuration and wording
109
+
110
+ - Every setting lives in `schema/config.yaml` and every visible string in
111
+ `text.yaml`, read through `t(key)`. Templates contain no literal copy, and
112
+ implementers override any key with `text:`. Copy that DGO Atlas writes must
113
+ always be overridable. Generated index pages also take a header and intro
114
+ from a content file at the same path.
115
+ - `dgo-atlas.example.yaml` at the repo root lists every setting at its
116
+ default. It is generated, and a test fails if it drifts. After changing
117
+ `config.yaml`, `viewmodel.yaml` or `text.yaml`, run
118
+ `uv run python -m dgo_atlas.generate`. Don't hide configuration behind the
119
+ CLI. If a setting exists, it must appear in the example file.
120
+
121
+ ## Command-line interfaces
122
+
123
+ Every CLI in this repository uses Typer. Do not add argparse, raw click
124
+ decorators or `sys.argv` parsing: `tests/test_cli.py::test_every_cli_is_typer`
125
+ fails if they appear under `src/`. Before adding a new script or entry point,
126
+ ask whether it belongs as a command in `src/dgo_atlas/cli/`.
127
+
128
+ - Commands live in `src/dgo_atlas/cli/`, one module per group, each with its
129
+ own `app = typer.Typer()`. `cli/__init__.py` only assembles them.
130
+ Scaffolding generators go in `cli/new.py` (`dgo-atlas new <thing>`).
131
+ - Keep commands thin. Parse options, call a library function (`build`,
132
+ `scaffold`, `editor`, `linkcheck`, `convert`, `text`, ...), print, and
133
+ `raise typer.Exit(code)`. Put the logic in the library module, not the
134
+ command.
135
+ - Declare options with `Annotated[..., typer.Option(help=...)]`. Shared
136
+ options, such as `--project`, live in `cli/common.py`. The docstring is the
137
+ command's help.
138
+ - Print through `dgo_atlas.console`, never bare `print`.
139
+ - Test commands with `typer.testing.CliRunner`.
140
+
141
+ `python -m dgo_atlas.generate` is the one separate Typer app, because it
142
+ rewrites files inside the package. See "Writing a command" in `docs/reference.md`.
143
+
144
+ ## Development
145
+
146
+ ```bash
147
+ uv sync
148
+ uv run pytest # needs network: imports DGO from its release URL
149
+ uv run python -m dgo_atlas.generate # after changing schema/viewmodel.yaml, schema/config.yaml or text.yaml
150
+ ```
151
+
152
+ - **One fixture.** `tests/fixtures/variant` is the only test fixture, and it
153
+ is also the preview site. Add test cases to it, or to a modified copy made
154
+ inside a test (see the `broken` fixture in `conftest.py`). Don't add new
155
+ fixture directories.
156
+ - **Preview.** The `preview` entry in `.claude/launch.json` builds the variant
157
+ into `.preview/` and serves it. Use it after any change to templates, CSS or
158
+ derivation.
159
+ - **Stale references.** `docs/reference.md` and the code cite "handoff §5" for the
160
+ original design. That handoff is no longer in the DGO repo, so treat the
161
+ reference and this file as current. `README.md` is for newcomers: keep it
162
+ short (under 250 words, plain language) and put details in the reference.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 James Geiger
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,99 @@
1
+ Metadata-Version: 2.5
2
+ Name: dgo-atlas
3
+ Version: 0.5.0
4
+ Summary: Govern a business glossary with the Data Governance Ontology (DGO) and publish it as a static site.
5
+ License-Expression: MIT
6
+ License-File: LICENSE
7
+ Requires-Python: >=3.10
8
+ Requires-Dist: jinja2>=3.1
9
+ Requires-Dist: linkml-runtime>=1.8
10
+ Requires-Dist: linkml==1.11.1
11
+ Requires-Dist: markdown-it-py>=3.0
12
+ Requires-Dist: pydantic>=2.0
13
+ Requires-Dist: pyyaml>=6.0
14
+ Requires-Dist: rdflib>=7.0
15
+ Requires-Dist: rich>=15.0.0
16
+ Requires-Dist: typer>=0.27.2
17
+ Description-Content-Type: text/markdown
18
+
19
+ # DGO Atlas
20
+
21
+ Publish your organization's business glossary as a website, with a clear
22
+ record of who owns each term and how it was approved.
23
+
24
+ ## What it does
25
+
26
+ A business glossary gives shared definitions for the words an organization
27
+ uses in its data: what counts as a "clinical trial," an "active student" or
28
+ "direct costs." Keeping those definitions consistent is hard when they live
29
+ in spreadsheets and wikis, where it isn't clear who owns a definition, whether
30
+ it's approved, or when it last changed.
31
+
32
+ With Atlas, you keep the glossary in plain text files in a Git repository.
33
+ Each term records its definition, who is responsible for it, and every step
34
+ of its review. Atlas checks the files for mistakes, such as a term that
35
+ refers to an owner who doesn't exist, and then builds a searchable static
36
+ website you can host anywhere, including GitHub Pages.
37
+
38
+ Because the glossary lives in Git, every change goes through a pull request
39
+ and has a full history.
40
+
41
+ ## Built on a shared standard
42
+
43
+ Your files follow the
44
+ [Data Governance Ontology](https://github.com/james-geiger/dgo) (DGO). DGO is
45
+ a published vocabulary that defines the parts of data governance, such as
46
+ terms, owners, stewards, councils and approval steps, and how they relate to
47
+ each other. You write in everyday words like `owner` or `approved`, and
48
+ Atlas translates them into DGO's standard definitions. That means other
49
+ tools can read and reuse your glossary without guessing what your fields
50
+ mean.
51
+
52
+ ## Get started
53
+
54
+ You need [uv](https://docs.astral.sh/uv/), a Python package manager.
55
+
56
+ ```bash
57
+ uvx dgo-atlas init my-glossary
58
+ cd my-glossary
59
+ uv run dgo-atlas build
60
+ ```
61
+
62
+ Open `site/index.html` to see the result. The new project includes example
63
+ terms, a sample council and a GitHub Actions workflow that builds the site on
64
+ every pull request.
65
+
66
+ Here is a small part of an example term:
67
+
68
+ ```yaml
69
+ glossary_terms:
70
+ - id: org:clinical-trial
71
+ label: clinical trial
72
+ definition: A research study in which participants are assigned to interventions...
73
+ responsibilities:
74
+ - type: owner
75
+ role_of: org:research-office
76
+ ```
77
+
78
+ ## Everyday commands
79
+
80
+ | Command | What it does |
81
+ | --- | --- |
82
+ | `dgo-atlas validate` | Check your files for mistakes |
83
+ | `dgo-atlas build` | Check your files, then build the site |
84
+ | `dgo-atlas convert -t ttl` | Export the glossary for other data tools |
85
+ | `dgo-atlas text` | List the site's wording, all of which you can change |
86
+
87
+ ## Settings
88
+
89
+ Titles, colors, fonts and page wording are customizable by changing the values in `dgo-atlas.yaml`. Every setting and its default is listed in
90
+ [dgo-atlas.example.yaml](dgo-atlas.example.yaml).
91
+
92
+ ## Learn more
93
+
94
+ - [DGO](https://github.com/james-geiger/dgo): the vocabulary your files follow
95
+
96
+
97
+ ## License
98
+
99
+ [MIT](LICENSE)
@@ -0,0 +1,81 @@
1
+ # DGO Atlas
2
+
3
+ Publish your organization's business glossary as a website, with a clear
4
+ record of who owns each term and how it was approved.
5
+
6
+ ## What it does
7
+
8
+ A business glossary gives shared definitions for the words an organization
9
+ uses in its data: what counts as a "clinical trial," an "active student" or
10
+ "direct costs." Keeping those definitions consistent is hard when they live
11
+ in spreadsheets and wikis, where it isn't clear who owns a definition, whether
12
+ it's approved, or when it last changed.
13
+
14
+ With Atlas, you keep the glossary in plain text files in a Git repository.
15
+ Each term records its definition, who is responsible for it, and every step
16
+ of its review. Atlas checks the files for mistakes, such as a term that
17
+ refers to an owner who doesn't exist, and then builds a searchable static
18
+ website you can host anywhere, including GitHub Pages.
19
+
20
+ Because the glossary lives in Git, every change goes through a pull request
21
+ and has a full history.
22
+
23
+ ## Built on a shared standard
24
+
25
+ Your files follow the
26
+ [Data Governance Ontology](https://github.com/james-geiger/dgo) (DGO). DGO is
27
+ a published vocabulary that defines the parts of data governance, such as
28
+ terms, owners, stewards, councils and approval steps, and how they relate to
29
+ each other. You write in everyday words like `owner` or `approved`, and
30
+ Atlas translates them into DGO's standard definitions. That means other
31
+ tools can read and reuse your glossary without guessing what your fields
32
+ mean.
33
+
34
+ ## Get started
35
+
36
+ You need [uv](https://docs.astral.sh/uv/), a Python package manager.
37
+
38
+ ```bash
39
+ uvx dgo-atlas init my-glossary
40
+ cd my-glossary
41
+ uv run dgo-atlas build
42
+ ```
43
+
44
+ Open `site/index.html` to see the result. The new project includes example
45
+ terms, a sample council and a GitHub Actions workflow that builds the site on
46
+ every pull request.
47
+
48
+ Here is a small part of an example term:
49
+
50
+ ```yaml
51
+ glossary_terms:
52
+ - id: org:clinical-trial
53
+ label: clinical trial
54
+ definition: A research study in which participants are assigned to interventions...
55
+ responsibilities:
56
+ - type: owner
57
+ role_of: org:research-office
58
+ ```
59
+
60
+ ## Everyday commands
61
+
62
+ | Command | What it does |
63
+ | --- | --- |
64
+ | `dgo-atlas validate` | Check your files for mistakes |
65
+ | `dgo-atlas build` | Check your files, then build the site |
66
+ | `dgo-atlas convert -t ttl` | Export the glossary for other data tools |
67
+ | `dgo-atlas text` | List the site's wording, all of which you can change |
68
+
69
+ ## Settings
70
+
71
+ Titles, colors, fonts and page wording are customizable by changing the values in `dgo-atlas.yaml`. Every setting and its default is listed in
72
+ [dgo-atlas.example.yaml](dgo-atlas.example.yaml).
73
+
74
+ ## Learn more
75
+
76
+ - [DGO](https://github.com/james-geiger/dgo): the vocabulary your files follow
77
+
78
+
79
+ ## License
80
+
81
+ [MIT](LICENSE)