README.md

# DMS3 Draft documentation

To add support diagrams in markdown documents, add Atom packages: "Markdown Preview Enhanced".

Use mkdocs to generate documentation site using markdown.

mkdocs setup:

References:
- https://www.mkdocs.org/
- https://www.mkdocs.org/user-guide/configuration/
- https://github.com/mkdocs/mkdocs/
- https://github.com/shd101wyy/markdown-preview-enhanced/blob/master/docs/diagrams.md

Use mkdocs pymdown-extensions with superfences and custom fences to support diagrams in mkdocs:
- https://facelessuser.github.io/pymdown-extensions/
- https://facelessuser.github.io/pymdown-extensions/extensions/superfences/
- https://mermaidjs.github.io/#/
- https://github.com/squidfunk/mkdocs-material/issues/693
- https://cdnjs.com/
- https://github.com/mermaid-https://www.digitalocean.com/community/tutorials/how-to-install-python-3-and-set-up-a-programming-environment-on-debian-10js/mermaid/

```bash
mkdir -p ~/Work/dapp/dms3
mkdir -p ~/Work/dapp/dms3/dms3-docs
cd ~/Work/dapp/dms3
```

Initial install was via cloning the repo as below.

Use clone of repo mermaid - cdnjs version has bad css that when a style is added to flowchart svg, the page is disabled. To build mermaid locally after cloning repo:

```bash
git clone https://github.com/mermaid-js/mermaid.git
cd mermaid/
nvm list
nvm use stable
npm install webpack
npm install yarn
npm run build
npm run release
ls -alg dist/
cp -v dist/mermaid.min.js* ../mkdocs-docs/docs/js/
cp -v dist/mermaid.js* ../mkdocs-docs/docs/js/

cd ../
python --version
pip --version
#sudo apt-get install python-pip
#
#wget https://bootstrap.pypa.io/get-pip.py
#sudo python get-pip.py
```

Later install followed this instead to setup a virtual python environment
- https://www.digitalocean.com/community/tutorials/how-to-install-python-3-and-
set-up-a-programming-environment-on-debian-10

```bash
sudo apt update
sudo apt -y upgrade
python3 -V
sudo apt install -y python3-pip
sudo apt install build-essential libssl-dev libffi-dev python3-dev
sudo apt install -y python3-venv
mkdir python_env
cd python_env
python3.7 -m venv mkdocs_env
ls mkdocs_env
source mkdocs_env/bin/activate
nano hello.py
  print("Hello, World!")
python hello.py

pip install mkdocs
mkdocs --version
mkdocs new mkdocs-docs
cd mkdocs-docs
mkdocs serve
pip install pymdown-extensions
pip install mkdocs-rtd-dropdown

mkdocs build
mkdocs serve
```
To support math rendering:
- https://stackoverflow.com/questions/27882261/mkdocs-and-mathjax/31926644
- https://squidfunk.github.io/mkdocs-material/extensions/pymdown/
- https://facelessuser.github.io/pymdown-extensions/extensions/arithmatex/

- roboto-slab fonts were downloaded from:
- Free download fonts at http://sharefonts.net
- unzip and move missing fonts into mkdocs-docs/docs/fonts/

## Usage

```bash
cd ~/Work/dapp/dms3-docs

# build
mkdocs build

# local live reload server
mkdocs serve # defaults to 127.0.0.1:8000
mkdocs serve --dev-addr=192.168.0.7:8000

# deploy
rsync -rv site/* gitlab.dms3.io:~/dms3-docs/site/
/sbin/apache2ctl restart
```