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 |
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.mdfrictionless_schemas('spec/**.schema.json')
"]
if_readme["index.mdinclude_file('README.md'}
"]
if_contributing["development.mdinclude_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