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 0000000..da7da0b Binary files /dev/null and b/docs/images/logo-manytask.png differ 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