From 100a0e08e538a062ec02fc51832b32a436b89683 Mon Sep 17 00:00:00 2001 From: sleep Date: Wed, 22 Jan 2025 14:59:51 +0100 Subject: [PATCH] Configured documentation website for ArmoniK.Admin.CLI --- docs/code_docs_gen.md | 41 ++++++++++++++++++++++ docs/development.md | 80 +++++++++++++++++++++++++++++++++++++++++++ docs/index.md | 46 +++++++++++++++++++++++++ docs/usage.md | 1 + mkdocs.yml | 30 ++++++++++++++++ pyproject.toml | 8 +++++ 6 files changed, 206 insertions(+) create mode 100644 docs/code_docs_gen.md create mode 100644 docs/development.md create mode 100644 docs/index.md create mode 100644 docs/usage.md create mode 100644 mkdocs.yml diff --git a/docs/code_docs_gen.md b/docs/code_docs_gen.md new file mode 100644 index 0000000..7dcd13c --- /dev/null +++ b/docs/code_docs_gen.md @@ -0,0 +1,41 @@ +::: armonik_cli.cli + +# Core + +## Exceptions + +::: armonik_cli.core.filters.SemanticError + +::: armonik_cli.exceptions.ArmoniKCLIError + +::: armonik_cli.exceptions.InternalError + +::: armonik_cli.exceptions.InternalArmoniKError + +::: armonik_cli.exceptions.NotFoundError + + +## Decorators + +The error handler decorator is supposed to serve as the object where all errors that happen during command execution are routed to. It helps make said errors more presentable. + +::: armonik_cli.core.decorators.error_handler + +Base command is a decorator that's used for all the commands in the ArmoniK CLI, it includes the error handler. + +::: armonik_cli.core.decorators.base_command + +## Options + +We've created some custom options that simplify the task of writing certain commands. + +::: armonik_cli.core.options.MutuallyExclusiveOption + + +## Filters + +The following classes are used for a custom Click parameter type that allows you to filter ArmoniK's objects based on specific conditions. + +::: armonik_cli.core.filters.FilterParser + +::: armonik_cli.core.filters.FilterTransformer diff --git a/docs/development.md b/docs/development.md new file mode 100644 index 0000000..68b8d0e --- /dev/null +++ b/docs/development.md @@ -0,0 +1,80 @@ +# Installing ArmoniK.Admin.CLI for development : + +### Requirements + +The CLI requires Python version 3.8 or newer. In order to install the ArmoniK CLI in an isolated environment, you must have python3-venv installed on your machine. + +```bash +sudo apt update && sudo apt install python3-venv +``` + +### Installation + +To install the CLI from source, first clone this repository. + +```bash +git clone git@github.com/aneoconsulting/ArmoniK.Admin.CLI.git +``` + +Navigate in the root directory + +```bash +cd ArmoniK.Admin.CLI +``` + +Create and activate the virtual environment + +```bash +python -m venv ./venv +source ./venv/bin/activate +``` + +Perform an editable install of the ArmoniK.Admin.CLI + +```bash +pip install -e . +``` + +### Running tests + +We use pytest for unit tests + +```bash +pytest tests/ +``` + +### Linting and formatting + +Install the development packages + +```bash +pip install '.[dev]' +``` + +Formatting +```bash +ruff format +``` + +Linting +```bash +ruff check . +``` + +### Documentation + +Install the documentation packages + +```bash +pip install '.[docs]' +``` + +Serving the documentation locally +```bash +mkdocs serve +``` + +Publishing the documentation to github pages +```bash +mkdocs gh-deploy +``` diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..7fe4bb4 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,46 @@ +# ArmoniK Admin CLI. + +This repository is part of the [ArmoniK](https://github.com/aneoconsulting/ArmoniK) project. It provides a command-line tool to monitor and manage ArmoniK clusters. + +## Installation + +### Requirements + +The CLI requires Python version 3.8 or newer. In order to install the ArmoniK CLI in an isolated environment, you must have python3-venv installed on your machine. + +```bash +sudo apt update && sudo apt install python3-venv +``` + +### Install from source + +To install the CLI from source, first clone this repository. + +```bash +git clone git@github.com/aneoconsulting/ArmoniK.Admin.CLI.git +``` + +Navigate in the root directory + +```bash +cd ArmoniK.Admin.CLI +``` + +Create and activate the virtual environment + +```bash +python -m venv ./venv +source ./venv/bin/activate +``` + +Install the CLI in the environment you just created. + +```bash +pip install . +``` + +## Contributing + +Contributions are always welcome! + +See [CONTRIBUTING](CONTRIBUTING.md) for ways to get started. \ No newline at end of file diff --git a/docs/usage.md b/docs/usage.md new file mode 100644 index 0000000..c57be47 --- /dev/null +++ b/docs/usage.md @@ -0,0 +1 @@ +`armonik -h` is your friend. \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..4c9cd34 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,30 @@ +site_name: Armonik Admin CLI +theme: material +nav: + - Home: index.md + - Usage : usage.md + - Development: development.md + - Code Documentation: code_docs_gen.md +repo_url: https://github.com/aneoconsulting/ArmoniK.Admin.CLI/ +repo_name: ArmoniK.Admin.CLI +markdown_extensions: + - admonition + - codehilite + - pymdownx.highlight: + anchor_linenums: true + line_spans: __span + pygments_lang_class: true + - pymdownx.inlinehilite + - pymdownx.snippets + - pymdownx.superfences + - pymdownx.details +plugins: + - search + - mkdocstrings: + default_handler: python + handlers: + python: + options: + show_symbol_type_toc: true + show_root_full_path: true + show_root_heading: true \ No newline at end of file diff --git a/pyproject.toml b/pyproject.toml index 62f0b9e..8ec1701 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -56,6 +56,14 @@ dev = [ 'ruff', 'types-PyYAML', ] +docs = [ + 'mkdocs', + 'mkdocs-material', + 'mkdocstrings', + 'mkdocstrings-python', + 'mkdocs-autorefs', + 'mkdocs-material' +] [project.scripts] armonik = "armonik_cli.cli:cli"