feat(docs): docs generation with MkDocs

.github/workflows/test.yml

@@ -90,11 +90,10 @@ jobs:
           cache: 'pip' # caching pip dependencies
       - name: Install dependencies
         run: |
-          echo "TODO: add docs dependencies"
-          # python -m pip install -e .[docs]
-      - name: TODO
+          python -m pip install -e .[docs]
+      - name: Build docs
         run: |
-          echo "TODO: add docs tests"
+          make docs-build
 
   docs-preview:
     runs-on: ubuntu-latest
@@ -108,6 +107,20 @@ jobs:
         run: |
           echo "TODO: add docs dependencies"
           # python -m pip install -e .[docs]
-      - name: TODO
+      - name: Docs preview
         run: |
-          echo "TODO: add docs preview"
+          mkdir -p site
+          make docs-build
+      - name: Publish to Cloudflare Pages
+        id: deploy
+        uses: cloudflare/pages-action@v1
+        with:
+          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+          projectName: manytask-checker
+          directory: ./site
+          # Optional: Enable this if you want to have GitHub Deployments triggered
+          gitHubToken: ${{ secrets.GITHUB_TOKEN }}
+          # Optional: Switch what branch you are publishing to.
+          # By default this will be the branch which triggered this workflow
+          branch: ${{ ( github.event.workflow_run.head_repository.full_name == github.repository && github.event.workflow_run.head_branch == 'main' && 'main' ) || ( github.event.workflow_run.head_sha ) }}

Makefile

@@ -49,15 +49,21 @@ format:
 	black checker tests
 	isort checker tests
 
+# Deploy the documentation
+docs-deploy:
+    @echo "[make] Deploying the documentation..."
+    mike deploy -b gh-pages `cat VERSION` --push
+    mike set-default `cat VERSION`
+
 # Build the documentation
 docs-build:
 	@echo "[make] Building the documentation..."
-	@echo "TODO"
+	mkdocs build
 
 # Serve the documentation in development mode
 docs-serve:
 	@echo "[make] Serve the documentation..."
-	@echo "TODO"
+	mkdocs serve
 
 
 .PHONY: all help test-unit test-integration test-docstests test lint format docs-build docs-serve

README.md

@@ -90,6 +90,6 @@ TBA
 ## Contributing
 
 Really appreciate any contributions!  
-For guidance on setting up a development environment see the [development guide](./docs/development.md).
+For guidance on setting up a development environment see the [development guide](./docs/5_development.md).
 For styleguide see organization [contribution guide](https://github.com/manytask/.github/CONTRIBUTING.md).
 

docs/3_plugins.md

@@ -10,18 +10,18 @@ You can refer to the [course-template](https://github.com/manytask/course-templa
 Plugin is a single stage of the pipeline, have arguments, return exclusion result. 
 In a nutshell, it is a Python class overriding abstract class `checker.plugins.PluginABC`:
 
-::: checker.plugins.PluginABC
+::: checker.plugins.base.PluginABC
     handler: python
 
 Note that each plugin should override `checker.plugins.PluginABC.Args` class to provide arguments validation. Otherwise, empty arguments will be passed to `run` method.
 
-::: checker.plugins.PluginABC.Args
+::: checker.plugins.base.PluginABC.Args
     handler: python
 
 
 Each plugin output `checker.plugins.PluginOutput` class when executed successfully. 
 
-::: checker.plugins.PluginOutput
+::: checker.plugins.base.PluginOutput
     handler: python
 
 In case of error, `checker.exceptions.PluginExecutionFailed` have to be raised.

docs/4_usage.md

@@ -3,15 +3,21 @@
 This section describes advanced usage of the checker.
 
 
-## CLI
+[//]: # (## CLI)
 
-The main checker functionality is available via CLI.
+[//]: # ()
+[//]: # (The main checker functionality is available via CLI.)
 
-::: mkdocs-click
-    :module: checker.__main__
-    :command: cli
-    :list_subcommands: True
-    :style: table
+[//]: # ()
+[//]: # (::: mkdocs-click)
+
+[//]: # (    :module: checker.__main__)
+
+[//]: # (    :command: cli)
+
+[//]: # (    :list_subcommands: True)
+
+[//]: # (    :style: table)
 
 
 ## Docker

docs/6_changelog.md

@@ -0,0 +1,4 @@
+{%
+   include-markdown "../CHANGELOG.md"
+   heading-offset=0
+%}

docs/index.md

@@ -0,0 +1,4 @@
+{%
+   include-markdown "../README.md"
+   heading-offset=0
+%}

mkdocs.yml

@@ -0,0 +1,90 @@
+site_name: Checker
+site_description: Python CLI script to run build and run tests against students solutions
+site_url: https://manytask.github.io/checker/
+
+docs_dir: ./docs
+site_dir: ./site
+
+theme:
+  name: material
+
+  palette:
+    # Palette toggle for light mode
+    - media: "(prefers-color-scheme: dark)"
+      scheme: default
+      toggle:
+        icon: material/lightbulb
+        name: Switch to dark mode
+      primary: teal
+      accent: purple
+
+    # Palette toggle for dark mode
+    - media: "(prefers-color-scheme: light)"
+      scheme: slate
+      toggle:
+        icon: material/lightbulb
+        name: Switch to light mode
+      primary: teal
+      accent: lime
+
+  features:
+    - navigation.tabs
+    - navigation.sections
+    - navigation.top
+    - search.suggest
+    - search.highlight
+    - content.tabs.link
+    - content.code.copy
+    - content.code.annotation
+
+  language: en
+
+  font:
+    text: Roboto
+    code: Roboto Mono
+
+  icon:
+    repo: fontawesome/brands/github
+
+  favicon: images/logo-manytask.png
+  logo: images/logo-manytask.png
+
+validation:
+  omitted_files: warn
+  absolute_links: warn
+  unrecognized_links: info
+
+extra:
+  version:
+    provider: mike
+
+repo_name: manytask/checker
+repo_url: https://github.com/manytask/checker
+
+nav:
+  - Overview: index.md
+  - Concepts: 0_concepts.md
+  - Getting started: 1_getting_started.md
+  - Configuration: 2_configuration.md
+  - Plugins: 3_plugins.md
+  - Usage: 4_usage.md
+  - Development: 5_development.md
+  - Changelog: 6_changelog.md
+
+markdown_extensions:
+  - pymdownx.details
+  - pymdownx.superfences
+  - pymdownx.highlight:
+      pygments_lang_class: true
+  - pymdownx.extra
+  - pymdownx.tabbed:
+      alternate_style: true
+  - mkdocs_click
+
+plugins:
+  - mike:
+      alias_type: symlink
+      canonical_version: latest
+  - search
+  - include-markdown
+  - mkdocstrings

pyproject.toml

@@ -39,6 +39,7 @@ dynamic = ["version"]
 
 [project.urls]
 Source = "https://github.com/yandexdataschool/checker"
+Documentation = "https://manytask.github.io/checker/"
 
 [project.optional-dependencies]
 test = [
@@ -54,6 +55,17 @@ test = [
     "types-PyYAML >=6.0.0,<7.0.0",
     "wheel >=0.40.0",
 ]
+docs = [
+    "mike >=1.1.0,<3.0.0",
+    "mkdocs >=1.4.0,<2.0.0",
+    "mkdocs-autorefs ==0.5.0",
+    "mkdocs-click >=0.8.0",
+    "mkdocs-include-markdown-plugin >=4.0.0,<7.0.0",
+    "mkdocs-material >=9.0.0,<10.0.0",
+    "mkdocs-material-extensions ==1.3.1",
+    "mkdocstrings ==0.24.0",
+    "mkdocstrings-python ==1.7.5",
+]
 
 [tool.setuptools.dynamic]
 version = {file = "VERSION"}
@@ -65,9 +77,6 @@ checker = "checker.__main__:cli"
 exclude = ["tests*"]
 
 
-# --------------------------------------------------------------------------- #
-
-
 [tool.mypy]
 no_incremental = true
 ignore_missing_imports = true