Skip to content

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
  • Sets up python
  • Loads resources from /docs/requirements.txt
  • Runs mike
/docs/requirements.txt Lists resources needed to generate documentation
/mkdocs.yml Controls mkdocs:
  • Defines look and feel of mkdocs
  • Specifies which mkdocs plug-ins to use
  • Specifies that mkdocs-macros should be used
  • Defines the structure of the documentation site
  • References /docs/*.md files as the major sections of the site
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
Overview of Documentation Building Process
/spec
/site: output of mkdocs
/docs
mkdocs-macros: run on execution of mkdocs
mkdocs: run on execution of mike
runs for current branch
specifieds parameters
plugin for
defines macros in code available for
specified in
specified in
specified in
specified in
*/schema.json
tides.spec.json
index.html
development.html
architecture.html
tables.html
index.md
architecture.md
tables.md
development.md
architecture.md
frictionless_spec('spec/tides.spec.json')
tables.md
frictionless_schemas('spec/**.schema.json')
index.md
include_file('README.md'}
development.md
include_file('contributing.md'}
mkdocs
mike
mkdocs.yml
mkdocs-macros
main.py
README.md
CONTRIBUTING.md