Merge pull request #238 from stakater/task/use-mkdocs-in-git-submodul…

…e-saap-docs-sa-5308

[Task] Use mkdocs in git submodule saap docs SA 5308

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "theme_common"]
+	path = theme_common
+	url = [email protected]:stakater/stakater-docs-mkdocs-theme.git

Dockerfile

@@ -1,6 +1,6 @@
 FROM python:3.12 as builder
 
-RUN pip3 install mkdocs-material mkdocs-mermaid2-plugin mkdocs-table-reader-plugin mkdocs-include-markdown-plugin
+RUN pip3 install mkdocs-mermaid2-plugin mkdocs-table-reader-plugin mkdocs-include-markdown-plugin
 
 # set workdir
 RUN mkdir -p $HOME/application
@@ -10,10 +10,10 @@ WORKDIR $HOME/application
 COPY --chown=1001:root . .
 
 # build the docs
+RUN chmod +x prepare_theme.sh && ./prepare_theme.sh
 RUN mkdocs build
-
 FROM nginxinc/nginx-unprivileged:1.26-alpine as deploy
-COPY --from=builder $HOME/application/site/ /usr/share/nginx/html/saap/
+COPY --from=builder $HOME/application/site/ /usr/share/nginx/html/
 COPY default.conf /etc/nginx/conf.d/
 
 # set non-root user

README.md

@@ -42,7 +42,13 @@ Install mkdocs-material and mermaid plugin:
 $ pip3 install mkdocs-material mkdocs-mermaid2-plugin
 ```
 
-Finally serve the docs using the built-in web server which is based on Python http server - note that the production build will use Nginx instead:
+Install mkdocs-include-markdown-plugin (if not installed by default and gives an error):
+
+```bash
+$ pip install mkdocs-include-markdown-plugin
+```
+
+Finally, serve the docs using the built-in web server which is based on Python http server - note that the production build will use Nginx instead:
 
 ```bash
 $ mkdocs serve
@@ -77,3 +83,11 @@ Install [Tilt](https://docs.tilt.dev/index.html), then run:
 ```bash
 $ tilt up
 ```
+
+Files `main.html` and `404.html` are served from `theme_common` rather than override since they are to be consistent throughout. If anything changes they can be served via `theme_override`.
+
+To execute the prepare theme command after setup you need to add the `prepare_theme.sh` or copy and paste bash file using sudo cmd file to your root directory and then run the following cmd:
+
+```bash
+$ chmod +x preparetheme sh
+```

prepare_theme.sh

@@ -0,0 +1,3 @@
+pip install -r theme_common/requirements.txt
+python theme_common/scripts/combine_theme_resources.py theme_common/resources theme_override/resources dist/_theme
+python theme_common/scripts/combine_mkdocs_config_yaml.py theme_common/mkdocs.yml theme_override/mkdocs.yml mkdocs.yml