diff --git a/.config/requirements-docs.txt b/.config/requirements-docs.txt new file mode 100644 index 0000000..47b3f73 --- /dev/null +++ b/.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 diff --git a/.github/workflows/tox.yml b/.github/workflows/tox.yml index 6811f71..c3b0cbf 100644 --- a/.github/workflows/tox.yml +++ b/.github/workflows/tox.yml @@ -38,6 +38,7 @@ jobs: max_python: "3.11" other_names: | lint + docs integration pkg diff --git a/.gitignore b/.gitignore index b9c2939..f02cc56 100644 --- a/.gitignore +++ b/.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 diff --git a/.readthedocs.yml b/.readthedocs.yml new file mode 100644 index 0000000..8262c4e --- /dev/null +++ b/.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 diff --git a/README.md b/docs/README.md similarity index 87% rename from README.md rename to docs/README.md index c9de255..fdf435b 100644 --- a/README.md +++ b/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 diff --git a/res/logo/android-chrome-192x192.png b/docs/images/android-chrome-192x192.png similarity index 100% rename from res/logo/android-chrome-192x192.png rename to docs/images/android-chrome-192x192.png diff --git a/res/logo/android-chrome-512x512.png b/docs/images/android-chrome-512x512.png similarity index 100% rename from res/logo/android-chrome-512x512.png rename to docs/images/android-chrome-512x512.png diff --git a/res/logo/apple-touch-icon.png b/docs/images/apple-touch-icon.png similarity index 100% rename from res/logo/apple-touch-icon.png rename to docs/images/apple-touch-icon.png diff --git a/res/logo/favicon-16x16.png b/docs/images/favicon-16x16.png similarity index 100% rename from res/logo/favicon-16x16.png rename to docs/images/favicon-16x16.png diff --git a/res/logo/favicon-32x32.png b/docs/images/favicon-32x32.png similarity index 100% rename from res/logo/favicon-32x32.png rename to docs/images/favicon-32x32.png diff --git a/res/logo/favicon.ico b/docs/images/favicon.ico similarity index 100% rename from res/logo/favicon.ico rename to docs/images/favicon.ico diff --git a/docs/images/logo.afdesign b/docs/images/logo.afdesign new file mode 100644 index 0000000..fe53f91 Binary files /dev/null and b/docs/images/logo.afdesign differ diff --git a/docs/images/logo.png b/docs/images/logo.png new file mode 100644 index 0000000..13aab10 Binary files /dev/null and b/docs/images/logo.png differ diff --git a/docs/images/logo.svg b/docs/images/logo.svg new file mode 100644 index 0000000..25d1e09 --- /dev/null +++ b/docs/images/logo.svg @@ -0,0 +1,12 @@ + + + + + + + diff --git a/docs/images/mk-social-preview.png b/docs/images/mk-social-preview.png new file mode 100644 index 0000000..02c09f3 Binary files /dev/null and b/docs/images/mk-social-preview.png differ diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css new file mode 100644 index 0000000..9b14d83 --- /dev/null +++ b/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); +} diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..1715ba1 --- /dev/null +++ b/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 diff --git a/pyproject.toml b/pyproject.toml index 4073ea0..8adb014 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -12,7 +12,7 @@ requires-python = ">=3.8" dynamic = ["version", "dependencies", "optional-dependencies"] name = "mk" description = "mk" -readme = "README.md" +readme = "docs/README.md" authors = [{ "name" = "Sorin Sbarnea", "email" = "sorin.sbarnea@gmail.com" }] license = { text = "MIT" } classifiers = [ @@ -82,6 +82,7 @@ disable = [ [tool.setuptools.dynamic] optional-dependencies.test = { file = [".config/requirements-test.txt"] } +optional-dependencies.docs = { file = [".config/requirements-docs.txt"] } dependencies = { file = [".config/requirements.in"] } [tool.setuptools_scm] diff --git a/test/test_cli.py b/test/test_cli.py index fdaf6ce..f2ad7ad 100644 --- a/test/test_cli.py +++ b/test/test_cli.py @@ -51,7 +51,7 @@ def do_complete() -> Optional[int]: assert result == 0 assert benchmark.stats["min"] > 0.0001 # seconds - assert benchmark.stats["mean"] < 0.0035 # seconds + assert benchmark.stats["mean"] < 0.005 # seconds @pytest.mark.parametrize( diff --git a/tox.ini b/tox.ini index 2f33f0b..8d0111f 100644 --- a/tox.ini +++ b/tox.ini @@ -1,8 +1,10 @@ [tox] envlist = lint + docs pkg py + integration minversion = 3.23.0 isolated_build = true skip_missing_interpreters = false @@ -47,6 +49,20 @@ setenv = commands = pip-compile --upgrade --resolver=backtracking --no-annotate --strip-extras --output-file=.config/requirements.txt --extra test setup.cfg +[testenv:docs] +description = Builds docs +extras = + docs +setenv = + # Disable colors until markdown-exec supports it: + # https://github.com/pawamoy/markdown-exec/issues/11 + NO_COLOR = 1 + TERM = dump +skip_install = false +usedevelop = true +commands = + mkdocs build {posargs:} + [testenv:lint] passenv = {[testenv]passenv} # without PROGRAMDATA cloning using git for Windows will fail with an