Skip to content

Updating Documentation

All documentation for etcd-druid resides in docs directory. If you wish to update the existing documentation or create new documentation files then read on.

Prerequisite: Setup Mkdocs locally

Material for Mkdocs is used to generate GitHub Pages from all the Markdown files present under the docs directory. To locally validate that the documentation renders correctly, it is recommended that you perform the following setup.

  • Install python3 if not already installed.
  • Setup a virtual environment via
Bash
python -m venv venv
  • Activate the virtual environment
Bash
source venv/bin/activate
  • In the virtual environment install the packages.
Bash
(venv) > pip install mkdocs-material
(venv) > pip install pymdown-extensions
(venv) > pip install mkdocs-glightbox
(venv) > pip install mkdocs-pymdownx-material-extras

Note

Complete list of packages installed should be in sync with Github Actions Configuration.

  • Serve the documentation

Bash
(venv) > mkdocs serve
You can now view the rendered documentation at localhost:8000. Any changes that you make to the docs will get hot-reloaded and you can immediately view the changes.

Updating Documentation

All documentation should be in markdown only. Ensure that you take care of the following:

  • The index.md is the home page for the documentation rendered as Github Pages. Please do not remove this file.
  • If you are using a new feature (that is not already used) by Mkdocs then ensure that it is properly configured in mkdocs.yml. Additionally, if new plugins or Markdown extensions are used, make sure that you update the Github Actions Configuration accordingly.
  • If new files are being added and you wish to show these files in Github Pages then ensure that you have added them under appropriate sections in the navigation section of mkdocs.yml.
  • If you are linking to any file outside the docs directory then relative links will not work on Github Pages. Please get the https link to the file or section of the file that you wish to link.

Raise a Pull Request

Once you have made the documentation changes then follow the guide on how to raise a PR.

Info

Once the documentation update PR has been merged, you will be able to see the updated documentation here.