Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 6 additions & 6 deletions .claude/launch.json
Original file line number Diff line number Diff line change
Expand Up @@ -2,15 +2,15 @@
"version": "0.0.1",
"configurations": [
{
"name": "mkdocs-en",
"runtimeExecutable": "mkdocs",
"runtimeArgs": ["serve", "-f", "config/en/mkdocs.yml", "--dev-addr", "127.0.0.1:8000", "--watch", "overrides", "--watch", "hooks", "--watch", "data", "--watch", "scripts"],
"name": "properdocs-en",
"runtimeExecutable": "properdocs",
"runtimeArgs": ["serve", "-f", "config/en/properdocs.yml", "--dev-addr", "127.0.0.1:8000", "--watch", "overrides", "--watch", "hooks", "--watch", "data", "--watch", "scripts"],
"port": 8000
},
{
"name": "mkdocs-en-alt",
"runtimeExecutable": "mkdocs",
"runtimeArgs": ["serve", "-f", "config/en/mkdocs.yml", "--dev-addr", "127.0.0.1:8001"],
"name": "properdocs-en-alt",
"runtimeExecutable": "properdocs",
"runtimeArgs": ["serve", "-f", "config/en/properdocs.yml", "--dev-addr", "127.0.0.1:8001"],
"port": 8001
}
]
Expand Down
32 changes: 32 additions & 0 deletions .github/ISSUE_TEMPLATE/specification-edit.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
name: Suggested change from a specification page
description: Filled in by "Suggest a change" on a specification's page in the MDIP registry (/specifications).
title: "Suggested change: "
labels: ["specification-registry", "suggested-change"]
body:
- type: markdown
attributes:
value: |
This form is filled in by the registry page. Submit it as it is: the
coalition reviews the change here in public, then applies it to the
specification's file in [`data/specifications/`](https://github.com/MobilityData/Mobility-Data-Interoperability-Principles/tree/main/data/specifications).
- type: input
id: spec_id
attributes:
label: Specification id
description: The file name in `data/specifications/`, without `.md`.
validations:
required: true
- type: textarea
id: change
attributes:
label: Proposed change
description: What the page shows today, what it should show, and the same change as it would be written in the file.
validations:
required: true
- type: textarea
id: evidence
attributes:
label: Sources
description: Links that support the change, such as a licence file, governance charter, changelog or adopters list.
validations:
required: false
2 changes: 1 addition & 1 deletion .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
__pycache__/
*.py[cod]

# MkDocs
# ProperDocs
site/
generated/
node_modules
Expand Down
4 changes: 2 additions & 2 deletions Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -11,8 +11,8 @@ setup:
pip3 install --upgrade --force-reinstall properdocs && \
pip3 install --upgrade --force-reinstall mkdocs-material

# --watch: mkdocs only watches docs/ and the config by itself, so the
# specification registry's sources (hooks/, scripts/, data/) have to be named. Note that mkdocs caches
# --watch: ProperDocs only watches docs/ and the config by itself, so the
# specification registry's sources (hooks/, scripts/, data/) have to be named. Note that ProperDocs caches
# the hook module -- an edit to hooks/ or scripts/ triggers a rebuild but the
# old code runs, so restart the server after changing those.
serve: clean
Expand Down
9 changes: 6 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -36,8 +36,10 @@ The `/specifications` page, one page per specification under
`/specifications/<id>/`, and a read-only JSON API under `/api/` are generated
at build time from the files in [`data/`](data/README.md). GitHub is the
source of truth and the place to contribute: each specification and each
organization is one Markdown file with YAML front matter, and "Suggest a
change" on a specification's page opens that file in GitHub's editor.
organization is one Markdown file with YAML front matter. "Suggest a change"
on a specification's page edits the page in place and sends the change as a
pre-filled GitHub issue; `/specifications/new/` does the same for a new
specification.

| Path | What it is |
| --- | --- |
Expand All @@ -49,7 +51,8 @@ change" on a specification's page opens that file in GitHub's editor.
| `scripts/spec_data.py` | Loads, validates and joins the files. |
| `scripts/spec_api.py` | Builds the `/api/` files: catalogue, full records, export CSV, the OpenAPI description, and its Swagger UI page at `/api/docs/`. |
| `scripts/check_specs.py` | `make specs-check`: validation, also run on every pull request. |
| `hooks/specifications.py` | MkDocs hook that renders the pages and publishes the API. |
| `hooks/specifications.py` | ProperDocs hook that renders the pages and publishes the API. |
| `overrides/assets/javascript/spec-editor.js` | The in-page editor behind "Suggest a change" and `/specifications/new/`. |

```bash
make specs-check # validate the data; fails on any unknown value or key
Expand Down
2 changes: 2 additions & 0 deletions config/en/properdocs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -64,11 +64,13 @@ extra_javascript:
- https://unpkg.com/mermaid@8.5.0/dist/mermaid.min.js
- assets/javascript/fix-md-search.js
- assets/javascript/specifications.js
- assets/javascript/spec-editor.js

extra_css:
- https://use.fontawesome.com/releases/v5.13.0/css/all.css
- assets/stylesheets/additional.css
- assets/stylesheets/specifications.css
- assets/stylesheets/spec-editor.css

markdown_extensions:
- attr_list
Expand Down
20 changes: 13 additions & 7 deletions data/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,13 +15,19 @@ folder on every build.

## How to contribute

- **Change an entry**: on the specification's page, "Suggest a change" opens
its file in GitHub's editor. Without write access to the repository, GitHub
offers to fork it and open a pull request, which is where the change is
reviewed.
- **Add a specification**: "Propose a specification" on the registry page
opens a new file with every field laid out. Name the file after the
specification's id.
- **Change an entry**: on the specification's page, "Suggest a change" makes
the page editable. Each value gets an edit button with a control that only
offers valid values, and values that depend on each other follow along (a
criterion that is not compliant makes the status not compliant, for
example). The change is sent as a pre-filled issue
([`specification-edit.yml`](../.github/ISSUE_TEMPLATE/specification-edit.yml))
showing what changes and the same change as YAML for the file. It is kept
in the browser until it is sent, so signing in or creating a GitHub account
does not lose it. Without JavaScript, the button opens the file in GitHub's
editor instead.
- **Add a specification**: "Propose a specification" opens
`/specifications/new/`, a blank page in the same editor. It sends the whole
new file, named after the registry id, as an issue.
- **Report a problem or ask a question**: open a
[change request](https://github.com/MobilityData/Mobility-Data-Interoperability-Principles/issues/new?template=specification-change.yml).

Expand Down
Loading
Loading