Documentation ΒΆ
The documentation for the TIDES specification is available at https://tides-transit.github.io/TIDES/ This site is automatically recreated each time a change is made to the specification.
When a change is pushed to the TIDES specification repository, Github Actions deployes the workflow docs.yml
that rebuilds the files for the TIDES documentation site. When a pull request is opened from a branch on the main repository, a draft version of the docs is built for preview purposes via the same process. For security purposes, documentation is not automatically built on pull requests opened from forks.
Files used in TIDES Documentation
Name | What it does |
---|---|
/.github/workflows/docs.yml |
|
/docs/requirements.txt |
Lists resources needed to generate documentation |
/mkdocs.yml |
Controls mkdocs:
|
main.py |
Defines macros used by mkdocs-macros, which can be referenced in the various markdown documentation files to generate markdown content, including from the Frictionless spec .json files |
/docs/*.md |
These markdown files contain the content for the documentation site, either directly or by reference. |
/docs/index.md |
Documentation homepage using content from README.me |
/docs/architecture.md |
Documents the overall spec architcture using a list of spec tables generated from tides.spec.json and diagrams the relationships between tables with mermaid |
/docs/tables.md |
Documents the detailed schemas for each table generated from /spec/*.schema.json |
/docs/development.md |
Documents spec development processes using content from CONTRIBUTING.md and CODE_OF_CONDUCT.md |
Tools Used in TIDES Documentation
Name | What it does |
---|---|
GitHub Actions | Runs following workflow on each push to the TIDES github repository: /.github/workflows/docs.yml |
mike | runs mkdocs and puts output in a folder in gh_pages branch which corresponds to the name of the branch (i.e. main, develop, pr-163, etc) For new branches with documentation, adds an entry in versions.json |
mkdocs |
Package which generates documentation from markdown and code |