Project¶
This is an example website of static generated website using MkDocs.
It demonstrates the application several seminal approaches and techniques. A summary of these is shown below. More details on these can be found in the Features section.
Project Features¶
Auto-generated documentation¶
The API Reference section contains the documentation automatically generated from each docstring in the Python code. This is built and compiled using the mkdocstrings package. For more details, refer to the Auto-documentation section.
Packaging¶
This project's packaging and dependency management is done using Poetry. More details can be found in the Packaging section.
Pre-commit hooks¶
This project uses pre-commit hooks. For more details on this subject, consult the Pre-commit hooks section.
CI-CD¶
The CI/CD pipeline for this project has been built using GitHub Actions. Details can be found here.
Make¶
For demonstration purposes, this project includes a Makefile as an alternative to Poetry scripts. Check the details here.
Unit testing¶
To show the proces of incorporating tests into a project, I have included some trivial unit tests. Additional info can be found here.
Project Layout¶
This section gives an overview of the layout of the repository.
Info
The code to generate this directory tree gets automatically executes and inserted upon building the documentation by the markdown-exec package.
[312K] .
├── [ 21K] .github
│ ├── [6.1K] ISSUE_TEMPLATE
│ │ ├── [1.1K] bug_report.yml
│ │ ├── [ 197] config.yml
│ │ └── [ 852] feature_request.yml
│ ├── [ 10K] workflows
│ │ ├── [2.5K] ci-cd.yml
│ │ ├── [1.1K] code-check.yml
│ │ └── [2.5K] dependency.yml
│ └── [ 505] PULL_REQUEST_TEMPLATE.md
├── [4.5K] .vscode
│ └── [ 537] settings.json
├── [ 91K] src
│ └── [ 87K] mkdocs_demo
│ ├── [4.0K] __pycache__
│ ├── [ 10K] config
│ │ ├── [4.0K] __pycache__
│ │ ├── [ 22] __init__.py
│ │ ├── [ 383] config.py
│ │ ├── [1.4K] interfaces.py
│ │ └── [ 275] trivial.py
│ ├── [ 39K] docs
│ │ ├── [6.2K] css
│ │ │ ├── [1.2K] mkdocstrings.css
│ │ │ └── [1.0K] style.css
│ │ ├── [ 18K] features
│ │ │ ├── [ 542] auto-documentation.md
│ │ │ ├── [3.6K] ci-cd.md
│ │ │ ├── [ 78] index.md
│ │ │ ├── [4.0K] make.md
│ │ │ ├── [2.6K] packaging.md
│ │ │ ├── [2.9K] pre-commit.md
│ │ │ └── [ 705] unit-testing.md
│ │ ├── [4.6K] images
│ │ │ └── [ 601] code-json.png
│ │ ├── [4.2K] overrides
│ │ │ └── [ 196] outdated.html
│ │ └── [2.0K] index.md
│ ├── [ 15K] lib
│ │ ├── [4.0K] __pycache__
│ │ ├── [ 20] __init__.py
│ │ ├── [ 922] factory.py
│ │ ├── [1.7K] mkdocstrings.py
│ │ └── [4.6K] superfluous.py
│ ├── [5.1K] scripts
│ │ ├── [ 24] __init__.py
│ │ ├── [ 209] gen_ref_pages.py
│ │ ├── [ 336] mkdocs.py
│ │ ├── [ 213] mypy.py
│ │ └── [ 298] precommit.py
│ ├── [4.1K] templates
│ │ └── [ 94] .gitkeep
│ ├── [ 27] __init__.py
│ └── [5.2K] mkdocs.yml
├── [8.3K] tests
│ ├── [4.3K] lib
│ │ ├── [ 0] __init__.py
│ │ └── [ 349] test_factory.py
│ └── [ 0] __init__.py
├── [ 20K] typings
│ └── [ 16K] mkdocs_demo
│ ├── [4.0K] config
│ ├── [4.0K] lib
│ └── [4.0K] scripts
├── [ 329] .editorconfig
├── [ 58] .env.example
├── [1.3K] .gitattributes
├── [ 116] .gitignore
├── [1.2K] .pre-commit-config.yaml
├── [1.1K] LICENSE
├── [1.4K] Makefile
├── [ 9] README.md
├── [2.5K] TODO.md
├── [ 128] cspell.config.yaml
├── [154K] poetry.lock
└── [1.6K] pyproject.toml
312K used in 25 directories, 51 files