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
flowchart LR subgraph mkdocs["mkdocs: run on execution of mike"] md_mike["mike"] -->|runs for current branch| md_mkdocs["mkdocs"] md_mkdocs.yml["mkdocs.yml"] -->|specifieds parameters| md_mkdocs["mkdocs"] md_mkdocs_macros["mkdocs-macros"] -->|"plugin for"| md_mkdocs["mkdocs"] main.py[/"main.py"/] -->|defines macros in code available for| md_mkdocs_macros["mkdocs-macros"] end subgraph mkdocs-macros["mkdocs-macros: run on execution of mkdocs"] if_spec["architecture.md
frictionless_spec('spec/tides.spec.json')"] if_schemas["tables.md
frictionless_schemas('spec/**.schema.json')"] if_readme["index.md
include_file('README.md'}"] if_contributing["development.md
include_file('contributing.md'}"] end subgraph "/docs" index.md[/"index.md"/] -->|specified in| md_mkdocs.yml[/"mkdocs.yml"/] architecture.md[/"architecture.md"/] -->|specified in| md_mkdocs.yml tables.md[/"tables.md"/] -->|specified in| md_mkdocs.yml development.md[/"development.md"/] -->|specified in| md_mkdocs.yml end subgraph site["/site: output of mkdocs"] index.html[/"index.html"/] development.html[/"development.html"/] architecture.html[/"architecture.html"/] tables.html[/"tables.html"/] end subgraph "/spec" spec[/"*/schema.json"/] schemas[/"tides.spec.json"/] end README[/"README.md"/]-->if_readme index.md-->if_readme if_readme --> index.html CONTRIBUTING[/"CONTRIBUTING.md"/]-->if_contributing development.md-->if_contributing if_contributing--> development.html tables.md-->if_schemas schemas-->if_schemas if_schemas--> tables.html architecture.md-->if_spec spec-->if_spec if_spec--> architecture.html