From 0f44568568e56bcf495ebb7dff2c775e6f0faa92 Mon Sep 17 00:00:00 2001 From: armantovmasyan Date: Sun, 17 Dec 2023 20:01:29 +0300 Subject: [PATCH] feat(docs): docs generation with MkDocs --- .github/workflows/test.yml | 25 +++++++--- Makefile | 10 +++- README.md | 2 +- docs/3_plugins.md | 6 +-- docs/4_usage.md | 20 +++++--- docs/6_changelog.md | 4 ++ docs/images/logo-manytask.png | Bin 0 -> 3873 bytes docs/index.md | 4 ++ mkdocs.yml | 90 ++++++++++++++++++++++++++++++++++ pyproject.toml | 15 ++++-- 10 files changed, 154 insertions(+), 22 deletions(-) create mode 100644 docs/images/logo-manytask.png create mode 100644 docs/index.md create mode 100644 mkdocs.yml diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 6b76334..55612d6 100644 --- a/.github/workflows/test.yml +++ b/.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 ) }} diff --git a/Makefile b/Makefile index 6ef3ba5..6cf5800 100644 --- a/Makefile +++ b/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 diff --git a/README.md b/README.md index f4d8020..2218ea1 100644 --- a/README.md +++ b/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). diff --git a/docs/3_plugins.md b/docs/3_plugins.md index 743ec89..9e1f76c 100644 --- a/docs/3_plugins.md +++ b/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. diff --git a/docs/4_usage.md b/docs/4_usage.md index 84ba082..cabd387 100644 --- a/docs/4_usage.md +++ b/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 diff --git a/docs/6_changelog.md b/docs/6_changelog.md index e69de29..dda7a1e 100644 --- a/docs/6_changelog.md +++ b/docs/6_changelog.md @@ -0,0 +1,4 @@ +{% + include-markdown "../CHANGELOG.md" + heading-offset=0 +%} \ No newline at end of file diff --git a/docs/images/logo-manytask.png b/docs/images/logo-manytask.png new file mode 100644 index 0000000000000000000000000000000000000000..da7da0b7ade8b411d6fc61557056e623492cb571 GIT binary patch literal 3873 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 O!)A2N3|ppmE9^i1F)(%j literal 0 HcmV?d00001 diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..1361910 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,4 @@ +{% + include-markdown "../README.md" + heading-offset=0 +%} \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..b44d91c --- /dev/null +++ b/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 \ No newline at end of file diff --git a/pyproject.toml b/pyproject.toml index 3c7e186..36b5416 100644 --- a/pyproject.toml +++ b/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