Add documentation for mk using mkdocs (#109)

.config/requirements-docs.txt

@@ -0,0 +1,11 @@
+cairosvg>=2.6.0
+markdown-exec>=1.3.0
+mkdocs-autorefs
+mkdocs-gen-files>=0.4.0
+mkdocs-htmlproofer-plugin>=0.10.2
+mkdocs-material-extensions>=1.1.1
+mkdocs-material>=9.0.13
+mkdocs>=1.4.2
+pillow>=9.4.0
+pipdeptree>=2.4.0
+pymdown-extensions>=9.9.2

.github/workflows/tox.yml

@@ -38,6 +38,7 @@ jobs:
           max_python: "3.11"
           other_names: |
             lint
+            docs
             integration
             pkg
 

.gitignore

@@ -1,12 +1,14 @@
-.tox
-build
-dist
-.eggs
-__pycache__
-src/mk.egg-info
+.DS_Store
 .cache
+.eggs
 .mypy_cache
+.tox
 .vscode
-.DS_Store
+__pycache__
+_readthedocs
+build
+dist
 report.html
+site
+src/mk.egg-info
 src/mk/_version.py

.readthedocs.yml

@@ -0,0 +1,26 @@
+---
+version: 2
+
+mkdocs:
+  fail_on_warning: true
+  configuration: mkdocs.yml
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+  commands:
+    - pip install --user tox
+    - python3 -m tox -e docs -- --strict --site-dir=_readthedocs/html/
+python:
+  system_packages: false
+  install:
+    - method: pip
+      path: tox
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs
+submodules:
+  include: all
+  recursive: true

README.md → docs/README.md

@@ -1,4 +1,4 @@
-# mk
+# Documentation of mk tool
 
 `mk` is a CLI tool that aims to ease contribution to any open-source project
 by hiding repository implementation details from the casual contributor.
@@ -38,27 +38,7 @@ pipx install mk
 
 ## Run it
 
-```text
-$ mk
-Usage: mk [OPTIONS] COMMAND [ARGS]...
-
-Options:
-  --version
-  -v, --verbose         Increase verbosity.  [default: 0]
-  --install-completion  Install completion for the current shell.
-  --show-completion     Show completion for the current shell, to copy it or
-                        customize the installation.
-
-  --help                Show this message and exit.
-
-Commands:
-  detect     Display detected information about current project.
-  lint       ... (from pre-commit)
-  lint2      ... (from tox)
-  pkg        ... (from tox)
-  py         ... (from tox)
-  up         Upload current change by creating or updating a CR/PR.
-```
+![](images/mk-social-preview.png)
 
 ## How it works
 

docs/stylesheets/extra.css

@@ -0,0 +1,174 @@
+/*
+Inspired by https://spec.draculatheme.com/ specification
+*/
+:root {
+  --ansi-red: #ff5555;
+  --ansi-green: #50fa7b;
+  --ansi-blue: #265285;
+  --ansi-yellow: #ffb86c; /* Orange */
+  --ansi-magenta: #bd93f9; /* Purple */
+  --ansi-cyan: #8be9fd;
+  --ansi-black: #282a36;
+  --ansi-white: #f8f8f2;
+}
+
+.-Color-Green,
+.-Color-Faint-Green,
+.-Color-Bold-Green {
+  color: var(--ansi-green);
+}
+.-Color-Red,
+.-Color-Faint-Red,
+.-Color-Bold-Red {
+  color: var(--ansi-red);
+}
+.-Color-Yellow,
+.-Color-Faint-Yellow,
+.-Color-Bold-Yellow {
+  color: var(--ansi-yellow);
+}
+.-Color-Blue,
+.-Color-Faint-Blue,
+.-Color-Bold-Blue {
+  color: var(--ansi-blue);
+}
+.-Color-Magenta,
+.-Color-Faint-Magenta,
+.-Color-Bold-Magenta {
+  color: var(--ansi-magenta);
+}
+.-Color-Cyan,
+.-Color-Faint-Cyan,
+.-Color-Bold-Cyan {
+  color: var(--ansi-cyan);
+}
+.-Color-White,
+.-Color-Faint-White,
+.-Color-Bold-White {
+  color: var(--ansi-white);
+}
+.-Color-Black,
+.-Color-Faint-Black,
+.-Color-Bold-Black {
+  color: var(--ansi-black);
+}
+
+.-Color-Faint {
+  opacity: 0.5;
+}
+
+.-Color-Bold {
+  font-weight: bold;
+}
+
+.-Color-Black-BGBlack,
+.-Color-BGBlack,
+.-Color-Red-BGBlack,
+.-Color-Green-BGBlack,
+.-Color-Yellow-BGBlack,
+.-Color-Blue-BGBlack,
+.-Color-Magenta-BGBlack,
+.-Color-Cyan-BGBlack,
+.-Color-White-BGBlack {
+  background-color: var(--ansi-black);
+}
+
+.-Color-Black-BGRed,
+.-Color-BGRed,
+.-Color-Red-BGRed,
+.-Color-Green-BGRed,
+.-Color-Yellow-BGRed,
+.-Color-Blue-BGRed,
+.-Color-Magenta-BGRed,
+.-Color-Cyan-BGRed,
+.-Color-White-BGRed {
+  background-color: var(--ansi-red);
+}
+
+.-Color-Black-BGGreen,
+.-Color-BGGreen,
+.-Color-Red-BGGreen,
+.-Color-Green-BGGreen,
+.-Color-Yellow-BGGreen,
+.-Color-Blue-BGGreen,
+.-Color-Magenta-BGGreen,
+.-Color-Cyan-BGGreen,
+.-Color-White-BGGreen {
+  background-color: var(--ansi-green);
+}
+
+.-Color-Black-BGYellow,
+.-Color-BGYellow,
+.-Color-Red-BGYellow,
+.-Color-Green-BGYellow,
+.-Color-Yellow-BGYellow,
+.-Color-Blue-BGYellow,
+.-Color-Magenta-BGYellow,
+.-Color-Cyan-BGYellow,
+.-Color-White-BGYellow {
+  background-color: var(--ansi-yellow);
+}
+
+.-Color-Black-BGBlue,
+.-Color-BGBlue,
+.-Color-Red-BGBlue,
+.-Color-Green-BGBlue,
+.-Color-Yellow-BGBlue,
+.-Color-Blue-BGBlue,
+.-Color-Magenta-BGBlue,
+.-Color-Cyan-BGBlue,
+.-Color-White-BGBlue {
+  background-color: var(--ansi-blue);
+}
+
+.-Color-Black-BGMagenta,
+.-Color-BGMagenta,
+.-Color-Red-BGMagenta,
+.-Color-Green-BGMagenta,
+.-Color-Yellow-BGMagenta,
+.-Color-Blue-BGMagenta,
+.-Color-Magenta-BGMagenta,
+.-Color-Cyan-BGMagenta,
+.-Color-White-BGMagenta {
+  background-color: var(--ansi-magenta);
+}
+
+.-Color-Black-BGCyan,
+.-Color-BGCyan,
+.-Color-Red-BGCyan,
+.-Color-Green-BGCyan,
+.-Color-Yellow-BGCyan,
+.-Color-Blue-BGCyan,
+.-Color-Magenta-BGCyan,
+.-Color-Cyan-BGCyan,
+.-Color-White-BGCyan {
+  background-color: var(--ansi-cyan);
+}
+
+.-Color-Black-BGWhite,
+.-Color-BGWhite,
+.-Color-Red-BGWhite,
+.-Color-Green-BGWhite,
+.-Color-Yellow-BGWhite,
+.-Color-Blue-BGWhite,
+.-Color-Magenta-BGWhite,
+.-Color-Cyan-BGWhite,
+.-Color-White-BGWhite {
+  background-color: var(--ansi-white);
+}
+
+.-Color-Black-BGBlack,
+.-Color-Red-BGRed,
+.-Color-Blue-BGBlue {
+  text-shadow: 0 0 1px var(--ansi-white);
+}
+
+.-Color-Green-BGGreen,
+.-Color-Yellow-BGYellow,
+.-Color-Cyan-BGCyan,
+.-Color-White-BGWhite,
+.-Color-Magenta-BGMagenta,
+.-Color-Cyan-BGGreen,
+.-Color-Green-BGCyan {
+  text-shadow: 0 0 1px var(--ansi-black);
+}

mkdocs.yml

@@ -0,0 +1,96 @@
+---
+site_name: mk tool documentation
+site_url: https://mk2.readthedocs.io/
+repo_url: https://github.com/pycontribs/mk
+edit_uri: blob/main/docs/
+copyright: Copyright © 2021-2023 Sorin Sbarnea
+docs_dir: docs
+strict: true
+
+extra_css:
+  - stylesheets/extra.css
+
+theme:
+  name: "material"
+  logo: images/logo.svg
+  favicon: images/favicon.ico
+  features:
+    - content.code.copy
+    - content.action.edit
+    - navigation.expand
+    - navigation.sections
+    - navigation.instant
+    - navigation.indexes
+    - navigation.tracking
+    - toc.integrate
+  palette:
+    - media: "(prefers-color-scheme: light)"
+      primary: blue-grey
+      accent: blue
+      scheme: default
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      primary: blue-grey
+      accent: blue
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
+extra:
+  social:
+    - icon: fontawesome/brands/python
+      link: https://pypi.org/project/mk/
+      name: PyPI
+    - icon: fontawesome/solid/scroll
+      link: https://github.com/pycontribs/mk/releases
+      name: Releases
+    - icon: fontawesome/solid/comments
+      link: https://github.com/pycontribs/mk/discussions
+      name: Discussions
+    - icon: fontawesome/brands/github-alt
+      link: https://github.com/pycontribs/mk
+      name: GitHub
+
+plugins:
+  - autorefs
+  - markdown-exec
+  - search
+  - social
+  - tags
+  # https://github.com/manuzhang/mkdocs-htmlproofer-plugin
+  - htmlproofer
+
+markdown_extensions:
+  - admonition
+  - def_list
+  - footnotes
+  - pymdownx.highlight:
+      anchor_linenums: true
+  - pymdownx.inlinehilite
+  - pymdownx.snippets:
+      check_paths: true
+  - pymdownx.superfences
+  - pymdownx.magiclink:
+      repo_url_shortener: true
+      repo_url_shorthand: true
+      social_url_shorthand: true
+      social_url_shortener: true
+      user: facelessuser
+      repo: pymdown-extensions
+      normalize_issue_symbols: true
+  - pymdownx.tabbed:
+      alternate_style: true
+  - toc:
+      toc_depth: 2
+      permalink: true
+  - pymdownx.superfences:
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:pymdownx.superfences.fence_code_format
+        - name: python
+          class: python
+          validator: !!python/name:markdown_exec.validator
+          format: !!python/name:markdown_exec.formatter