Documentation Overview
How I built and deployed this documentation
Idealization
To create this documentation I used mkdocs, a static site generator which uses Markdown format to write the files and it is built using a single yaml configuration file, with mkdocs-material customized theme. Mkdocs requires a recent version of python, I used python3.7.
Local development
Folder structure:
documentation
│ ...
│ ...
│
└───docs # main folder
│ │ README.md
│ │ requirements.txt # requirements
│ │ mkdocs.yml # configuration file
│ │
│ └───docs # configuration file points to this folder
│ │ {documentation files} # folders and Markdown files
Optional Step
I created and activated a new python virtual environment.
Used the package manager pip to install requirements.
To build documentation and host it locally, I used both of this commands:
Documentation deploy
To build the documentation, mkdocs creates a new folder site/
which contains all the HTML, CSS and JS files that are created with the build
command. To deploy this documentation in git, I created a new github pages
instance, which points to gh-pages
git branch. This git branch contains the site/
files.
%%{init: {'logLevel': 'debug', 'theme': 'neutral', 'gitGraph': {'showBranches': true, 'showCommitLabel': true}}}%%
gitGraph
commit id: "a"
commit id: "docs folder" type: HIGHLIGHT
branch gh-pages
checkout gh-pages
commit id: "update site folder"
checkout main
commit id: "c"
After the commit in the docs/
main folder, a Github Actions workflow is triggered in which:
- Requirements are installed;
- Command
mkdocs gh-deploy
runs and updates thegh-pages
branch with thesite/
folder.
name: build and deploy - mkdocs
on:
push:
branches:
- main
paths:
- 'docs/**'
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- uses: actions/setup-python@v2
with:
python-version: 3.x
- run: |
cd docs
pip install -r requirements.txt
mkdocs gh-deploy --force --clean --verbose
Afterwards, the documentation site https://joaohb07.github.io/documentation is updated by gh-pages
branch.
Contributing
Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.
Please make sure to update tests as appropriate.