From 088669a5ef3b7039f5eb8e49bb952b445556c919 Mon Sep 17 00:00:00 2001
From: prasadtalasila <prasad.talasila@gmail.com>
Date: Wed, 27 Sep 2023 14:48:46 +0200
Subject: [PATCH] Corrects docs/ publish instructions

---
 docs/PUBLISH.md | 40 +++++++++++++++++++++++++++++++++-------
 1 file changed, 33 insertions(+), 7 deletions(-)

diff --git a/docs/PUBLISH.md b/docs/PUBLISH.md
index 105a075ac..bd36dc85d 100644
--- a/docs/PUBLISH.md
+++ b/docs/PUBLISH.md
@@ -1,12 +1,15 @@
 
 # Project Documentation
 
-This file contains instructions for creation, compilation and publication of project documentation.
+This file contains instructions for creation, compilation and publication of
+project documentation.
 
-The documentation system is based on [Material for Mkdocs](https://squidfunk.github.io/mkdocs-material/). The documentation is generated based on the configuration files:
+The documentation system is based on
+[Material for Mkdocs](https://squidfunk.github.io/mkdocs-material/).
+The documentation is generated based on the configuration files:
 
 * **mkdocs.yml**: used for generating online documentation which is hosted on the web
-* **mkdocs_offline.yml**: used for generating offline documentation that can be downloaded and used on user computer.
+* **mkdocs-github.yml**: used for generating documentation in github actions
 
 Install Mkdocs using the following command.
 
@@ -16,7 +19,23 @@ pip install -r docs/requirements.txt
 
 ## Create documentation
 
-You can add, and edit the markdown files in `docs/` directory to update the documentation. There is a facility to check the status of your documentation by using:
+The document generation pipeline can generate both **html** and **pdf**
+versions of documentation.
+
+The generation of **pdf** version of documentation is controlled via
+a shell variable.
+
+```bash
+export MKDOCS_ENABLE_PDF_EXPORT=0 #disables generation of pdf document
+export MKDOCS_ENABLE_PDF_EXPORT=1 #enables generation of pdf document
+```
+
+The `mkdocs` utility allows for live editing of documentation
+on the developer computer.
+
+You can add, and edit the markdown files in `docs/` directory to update
+the documentation. There is a facility to check the status of your
+documentation by using:
 
 ```bash
 mkdocs serve --config-file mkdocs.yml
@@ -24,16 +43,23 @@ mkdocs serve --config-file mkdocs.yml
 
 ## Publish documentation
 
-You can compile and place the html version of documentation on the `webpage-docs` branch of the codebase.
+You can compile and place the html version of documentation on
+the `webpage-docs` branch of the codebase.
 
 ```bash
+export MKDOCS_ENABLE_PDF_EXPORT=1 #enable generation of pdf document
 source script/docs.sh [version]
 ```
 
-The command takes an optional version parameter. This version parameter is needed for making a release. Otherwise, the documentation gets published with the latest version tag. This command makes a new commit on `webpage-docs` branch. You need to push the branch to upstream.
+The command takes an optional version parameter. This version parameter is needed
+for making a release. Otherwise, the documentation gets published with
+the latest version tag. This command makes a new commit on `webpage-docs` branch.
+You need to push the branch to upstream.
 
 ```bash
 git push webpage-docs
 ```
 
-The github pages system serves the [project documentation](https://into-cps-association.github.io/DTaaS/) from this branch.
+The github pages system serves the
+[project documentation](https://into-cps-association.github.io/DTaaS/) from
+this branch.