to support diagrams in markdown documents, add atom package:
"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/
mkdir -p ~/Work/dapp/dms3 mkdir -p ~/Work/dapp/dms3/mkdocs-docs cd ~/Work/dapp/dms3
#Note: mermaid was removed after the mkdocs documentation was functional #initially the docs folder was setup as ~/Work/dapp/dms3/mkdocs-docs, #but later moved to ~/Work/dapp/dms3-docs
#Note: 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:
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
follow 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 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
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