Documentation
Our documentation is built using mkdocs, which renders markdown files into HTML/CSS files.
The markdown files powering the documentation are in the same repository, under the docs/ directory. Along with this file, there is the mkdocs.yml configuration file, which organizes the markdown files hierarchically, sets the site theme, and much more.
Whenever you do substantial changes to the ETL project, make sure that this is reflected in the documentation
That is, whenever you are working on a project and you create a pull request, make sure that the documentation still makes sense with your changes. If necessary, adapt it in the same PR.
Updating the documentation
First, make sure that you have all the development libraries installed
poetry install --with dev
Preview the documentation
Next, to preview the documentation on your local machine, run
mkdocs serve
and go to localhost:8000.
Now, you can test this by modifying one of the files in docs/ and see how this is reflected automatically on the local site.
Adding a new entry
To add a new entry, simply create a markdown file in the docs/ directory (or a directory that falls under it). Next, if you want this entry to be listed in the navigation bar, you'll need to add a reference to the file in the mkdocs.yml file.
Update the metadata reference
All the reference documentation is generated using the schema files (see files under the schemas directory). If you want to tweak the description, examples or other fields in the reference, please take a look at this guideline.
Pull request
Once you are happy with your documentation tweaks, make sure to create a pull request so that others can review your text.