Merge pull request #39 from LinuxJedi/document-documentation

Document the documentation

Author: lealem47

CONTRIBUTING.md

@@ -0,0 +1,167 @@
+# Contributing
+
+## Editing Documentation
+
+For each documentation directory you will find a `src` directory which contains chapter files. You can edit these chapter files to change the content.
+
+The documentation uses [Python Markdown](https://python-markdown.github.io/) for the HTML documentation and [Pandoc's Markdown](https://pandoc.org/MANUAL.html#pandocs-markdown) for the PDF documentation. Any edits should strive to be compatible with both (for most things these two are compatible with each other).
+
+## New Manual
+
+### Files Needed
+
+As a minimum a manual directory needs:
+
+* header.txt
+* mkdocs.yml
+* Makefile
+* src directory
+
+#### header.txt
+
+The `header.txt` needs to have the following content (adjust the title for your manual). This is needed to generate the PDF output:
+
+```
+% wolfBoot Documentation  ![](logo.png)
+
+---
+header-includes:
+    # Blank pages on new sections
+    - \usepackage{titlesec}
+    - \newcommand{\sectionbreak}{\clearpage}
+    # Fancy page headers
+    - \usepackage{fancyhdr}
+    - \pagestyle{fancy}
+    - \fancyfoot[LO,RE]{COPYRIGHT \copyright 2021 wolfSSL Inc.}
+    # Wrap long syntax highlighting code blocks
+    - \usepackage{fvextra}
+    - \DefineVerbatimEnvironment{Highlighting}{Verbatim}{breaklines,commandchars=\\\{\}}
+    # Wrap long non-sytax highlighted code blocks
+    - \usepackage{listings}
+    - \let\verbatim\undefined
+    - \let\verbatimend\undefined
+    - \lstnewenvironment{verbatim}{\lstset{breaklines,basicstyle=\ttfamily}}{}
+subparagraph: yes
+---
+```
+
+#### mkdocs.yml
+
+The `mkdocs.yml` file defines the layout for the HTML documentation output. It should be as below with the `site_name` and `nav` adjusted for your documentation. It can contain nested navigation, see `wolfSSL/mkdocs.yml` for a more complex example.
+
+Your first documentation file in the `Makefile` will be renamed `index.md` for the HTML build.
+
+```
+site_name: wolfBoot Manual
+site_url: https://wolfssl.com/
+docs_dir: build/html/
+site_dir: html/
+copyright: wolfSSL Inc. 2021
+nav:
+    - "1. Introduction": index.md
+    - "2. Compiling wolfBoot": chapter02.md
+    - "3. Targets": chapter03.md
+    - "4. Hardware Abstraction Layer": chapter04.md
+    - "5. Flash Partitions": chapter05.md
+    - "6. wolfBoot Features": chapter06.md
+    - "7. Integrating wolfBoot in an existing project": chapter07.md
+    - "8. Troubleshooting": chapter08.md
+theme:
+  name: null
+  custom_dir: ../mkdocs-material/material
+  language: en
+  palette:
+    primary: indigo
+    accent: indigo
+  font:
+    text: Roboto
+    code: Roboto Mono
+  icon: "logo.png"
+  logo: logo.png
+  favicon: logo.png
+  feature:
+    tabs: true
+extra_css: [skin.css]
+extra:
+    generator: false
+use_directory_urls: false
+```
+
+#### Makefile
+
+The following is a minimal `Makefile` for a project:
+
+```
+-include ../common/common.am
+.DEFAULT_GOAL := all
+all: pdf html
+
+
+SOURCES = chapter01.md \
+		  chapter02.md \
+		  chapter03.md \
+		  chapter04.md \
+          chapter05.md \
+          chapter06.md \
+          chapter07.md \
+          chapter08.md
+
+PDF = wolfBoot-Manual.pdf
+
+.PHONY: html-prep
+html-prep:
+
+.PHONY: pdf-prep
+pdf-prep:
+```
+
+The `common.am` contains has a lot of content to process the Markdown files into the HTML and PDF outputs. The `SOURCES` list should be changed to a list of your source Markdown files in the order you wish them to be rendered for the PDF. The `PDF` variable should be changed to your PDF output filename.
+
+The `html-prep` should contain any additional steps you wish to make prior to rendering the HTML output and likewise the `pdf-prep` should contain additional steps for the PDF output.
+
+There are more complex examples which also pull in Doxygen content from the project source code for appendices in `wolfTPM/Makefile` and `wolfSSL/Makefile`.
+
+#### src Directory
+
+The `src` directory contains the source Markdown documentation that will be compiled into PDF and HTML manuals.
+
+### Docker Builds
+
+The build process is quite complex with several required dependencies, particularly for the manuals that require Doxygen. Therefore a Docker based build has been created which will do all the hard work automatically without you having to install any dependencies (apart from Docker itself).
+
+For every manual an entry needs to be added into the `Dockerfile` and `Makefile` at the root of this directory tree.
+
+#### Dockerfile
+
+A new entry needs to be added as below (modified for the project name / directories / files):
+
+```
+# Build wolfBoot PDF
+FROM builder AS wolfboot-stage1
+WORKDIR /src/wolfssl/wolfBoot
+RUN make pdf
+
+# Build wolfBoot HTML
+FROM builder AS wolfboot-stage2
+WORKDIR /src/wolfssl/wolfBoot
+RUN make html
+
+# Build wolfBoot HTML and PDF
+FROM scratch AS wolfboot
+COPY --from=wolfboot-stage1 /src/wolfssl/wolfBoot/wolfBoot-Manual.pdf wolfboot.pdf
+COPY --from=wolfboot-stage2 /src/wolfssl/wolfBoot/html wolfboot-html
+```
+
+The final `wolfboot.pdf` and `wolfboot-html` will be what is created in the `build` directory in the root of this directory tree at the end of the build.
+
+#### Makefile
+
+An entry also needs to be added to the `Makefile` at the root of this directory tree with the following contents (adjusted for the target at the third step of your Dockerfile entry):
+
+```
+.PHONY: wolfboot
+wolfboot: build
+	@$(DOCKER_CMD) --target=wolfboot
+```
+
+You will also need to add an entry to the `all` line for your project.

README.md

@@ -1,19 +1,66 @@
 # Documentation
 
-## wolfSSL Directory
+This is the new build system for the various wolfSSL products' manuals, please see the READMEs each directory for more information. The advantages of this over previous wolfSSL manuals are:
 
-This is the new build system for the various wolfSSL products' manuals, please see the READMEs each directory for more information.
+* Has a possible code review process
+* Can automatically generate PDF and HTML output
+* Has cross links between parts of the documentation
+* Has links to the required API parts
 
-## Site styling
+## Building Documentation
 
-To generate wolfSSL themed html docs, you'll need the mkdocs-material submodule. To get the repo, you can either:
+To build the documentation you will need Docker running on your system. In this documentation root directory run `make` to build the documentation for every project which will output in a `build` subdirectory of this root directory (**note**: on some systems you may need to use `sudo` before `make`). You can also build individual project manuals by doing:
 
-1. Clone the documentation repo recursively.
+* `make wolfssl`
+* `make wolfssh`
+* `make wolfboot`
+* `make wolfclu`
+* `make wolfcrypt-jni`
+* `make wolfmqtt`
+* `make wolfsentry`
+* `make wolfssl-jni`
+* `make wolftpm`
 
-`git clone --recursive <repo url>`
+## Contributing
 
-2. Update the submodules, if documentation repo is already cloned.
+There is a [CONTRIBUTING.md](CONTRIBUTING.md) document which outlines how to add manuals to the tree.
 
-`git submodule update --recursive`
+## Building without Docker
 
-Then just run `make html` for the desired manual.
+### Pre-requisites
+
+If you are not building using the Docker build system above you can build using Ubuntu, this will require around 3GB of packages to be installed:
+
+```sh
+sudo apt install pandoc texlive-full mkdocs doxygen
+```
+
+You also need Doxybook2 installed which can be found at: <https://github.com/matusnovak/doxybook2>. Unfortunately there is no package for this. Installation instructions can be found at: <https://github.com/matusnovak/doxybook2#Install>
+
+If Doxybook2 is installed in a non-stardard path you can use the environment variable `DOXYBOOK_PATH` to set it.
+
+### Building
+
+When in each manual directory to build the PDF:
+
+```sh
+make pdf
+```
+
+To build the HTML:
+
+```sh
+make html
+```
+
+To build both:
+
+```sh
+make
+```
+
+To run a local HTML server (HTML is built to a temporary area for this):
+
+```sh
+make serve
+```