diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 0000000..8293e95 --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,51 @@ +name: Deploy Documentation + +on: + push: + tags: + - "v*" + workflow_dispatch: + +permissions: + contents: read + pages: write + id-token: write + +jobs: + build: + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - name: Setup Python + uses: actions/setup-python@v4 + with: + python-version: '3.11' + + - name: Install dependencies + run: pip install -r docs-requirements.txt + + - name: Build documentation + run: mkdocs build + + - name: Upload artifact + uses: actions/upload-pages-artifact@v2 + with: + path: ./site + + deploy: + needs: build + runs-on: ubuntu-latest + if: github.ref == 'refs/heads/main' + + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v2 \ No newline at end of file diff --git a/.gitignore b/.gitignore index deb55b2..b22fdc3 100644 --- a/.gitignore +++ b/.gitignore @@ -45,4 +45,4 @@ env.bak/ venv.bak/ # SonarQube -.scannerwork/ \ No newline at end of file +.scannerwork/site/ diff --git a/docs-requirements.txt b/docs-requirements.txt new file mode 100644 index 0000000..ed54aec --- /dev/null +++ b/docs-requirements.txt @@ -0,0 +1,7 @@ +mkdocs==1.6.1 +mkdocs-autorefs==1.4.3 +mkdocs-click==0.9.0 +mkdocs-get-deps==0.2.0 +mkdocs-material==9.6.19 +mkdocs-material-extensions==1.3.1 +mkdocstrings==0.30.0 diff --git a/docs/commands.md b/docs/commands.md new file mode 100644 index 0000000..6b7e706 --- /dev/null +++ b/docs/commands.md @@ -0,0 +1,11 @@ +# oks-cli commands reference + +This page provides documentation for `oks-cli` commands and subcommands. + +::: mkdocs-click + :module: oks_cli.main + :command: cli + :prog_name: oks-cli + :style: table + :depth: 1 + :list_subcommands: True diff --git a/docs/contributing.md b/docs/contributing.md new file mode 100644 index 0000000..b77c54f --- /dev/null +++ b/docs/contributing.md @@ -0,0 +1,170 @@ +# Contribution Guide + +Thank you for your interest in contributing to the OKS-CLI Project ! This document describes how you can participate and help us improve the project. + +## Table of Contents + +- [How to contribute](#how-to-contribute) +- [Report bugs](#report-bugs) +- [Suggest features](#suggest-features) +- [Development](#development) +- [Pull request process](#pull-request-process) +- [Code standards](#code-standards) + +## How to contribute + +There are several ways to contribute to this project: + +- **Report bugs** - Help us identify and fix issues +- **Suggest new features** - Propose improvements and new functionality +- **Improve the documentation** - Make our guides clearer and more helpful + +## Report bugs + +Before reporting a bug, check that it has not already been reported by consulting existing issues. + +### How to report a bug + +Suggestions for improvements are welcome! Before reporting a bug : + +1. Check if the Bug has already been reported +1. Use the "Bug Report" issue template +2. Provide a clear and concise description of the problem +3. Include steps to reproduce the bug +4. Describe the actual behavior +5. Describe the expected behavior +6. Specify your environment (OS, oks-cli version, terminal, etc.) +7. Attach any relevant logs, screenshots, or error messages + +## Suggest features + +Suggestions for improvements are welcome! Before proposing a feature : + +1. Check if the Feture has already been reported +2. Use the "Feature Request" issue template +3. Clearly describe the problem your proposal solves +4. Explain your proposed solution +5. Mention any alternatives you considered +6. Wait for feedback from the team — or, if you're ready, implement the feature yourself by opening a pull request + +## Development + +### Prerequisites + +Before you start development, make sure you have : + +- Python 3.11 or newer +- Pip + +### Environment configuration + +```bash +# Clone the repository +git clone https://github.com/outscale/oks-cli.git +cd oks-cli + +# Create a virtual environment +python -m venv venv + +# Activate your virtual environment +source venv/bin/activate + +# Install dependencies +pip install -r requirements.txt + +# Install in editable mode +pip install -e . +``` + +### Project Structure + +``` +oks-cli/ +├── oks_cli/ # Main source code +│ ├── __pycache__/ # Compiled Python files +│ ├── __init__.py # Package initialization +│ ├── cache.py # Cache management functionality +│ ├── cluster.py # Cluster operations +│ ├── main.py # Main CLI entry point +│ ├── profile.py # Profile management +│ ├── project.py # Project configuration +│ ├── quotas.py # Quota management +│ └── utils.py # Utility functions +├── setup.py # Dependencies configuration +├── requirements.txt # Dependencies list +├── CONTRIBUTING.md # This file +└── README.md # Documentation +``` + +## Pull request process + +### Before submitting + +1. Fork the repository +2. Create a branch for your feature (git checkout -b feature) +3. Commit your changes (git commit -m 'Adding my feature') +4. Push it to your branch (git push origin feature) +5. Open a Pull Request + +### Acceptance criteria + +- The code follows the project's Python conventions and CLI architecture +- Documentation is updated as needed +- Commits are well formatted +- No merge conflicts + +### Description of PR + +Use the provided template and include: + +- **Summary** of changes +- **Type of change** (bug fix, new feature, breaking change, etc.) +- **Tests** performed +- **Screenshots** if applicable +- **Related issues** (e.g., "Fixes #123") + +## Code standards + +### Code style + +- Follow project naming conventions +- Use configured linting tools (PEP8) +- Respect existing indentation and formatting +- Comment out complex code + +### Commit message + +Use the conventional format : + +``` +git commit -m "feat: brief description of your functionality" +``` + +Accepted types : `feat`, `fix`, `docs`, `style`, `refactor`, `test` + +### Documentation + +- Update documentation as needed +- Use **docstrings** for public functions and classes +- Keep README.md up to date + +## Review process + +1. **Manual testing** : The CLI should be tested locally. Verify that the commands work and do not generate errors. +2. **Review by someone from our team** : A member of our team will review the PR to ensure the code is clear and consistent. +3. **Merge** : A maintainer merges the PR after validation. + +## Questions ? + +If you have questions not covered in this guide : + +- Consult [existing issues](https://github.com/outscale/oks-cli/issues) +- Contact [support](https://docs.outscale.com/fr/userguide/Support-technique.html) + +## Thanks + +Thank you to all the contributors who help improve this project! 🚀 + +--- + +By contributing to this project, you agree that your contributions are licensed under the same license as the project. \ No newline at end of file diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..cfedcf7 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,83 @@ +# Welcome to `oks-cli` + +[![Project Incubating](https://docs.outscale.com/fr/userguide/_images/Project-Incubating-blue.svg)](https://docs.outscale.com/en/userguide/Open-Source-Projects.html) +[![](https://dcbadge.limes.pink/api/server/HUVtY5gT6s?style=flat&theme=default-inverted)](https://discord.gg/HUVtY5gT6s) + +

+ Kubernetes +

+ +## 🧭 Overview + +**`oks-cli`** is a command-line interface that allows you to deploy and manage Kubernetes clusters on top of OUTSCALE infrastructure using [OKS](https://docs.outscale.com/en/userguide/OUTSCALE-Kubernetes-as-a-Service-OKS.html) (OUTSCALE Kubernetes as a Service). + +## 🚀 Usage + +Display all available commands: + +```bash +oks-cli fullhelp +``` + +### Commands + +A complete description and available options for each commands is available in the [Commands](./commands.md) page + +| Command | Description | +|--------------------------------------|---------------------------------------------------------------| +| profile list | List existing profiles | +| profile add | Add AK/SK or username/password new profile | +| profile delete | Delete a profile by name | +| profile update | Update an existing profile | +| project list | List all projects | +| project create | Create a new project | +| project get | Get default project or the project by name | +| project update | Update a project by name | +| project delete | Delete a project by name | +| project login | Set a default project by name | +| project logout | Unset default project | +| project quotas | Get project quotas | +| project snapshots | Get project snapshots | +| project publicips | Get project public ips | +| cluster list | List all clusters | +| cluster create | Create a new cluster | +| cluster get | Get a cluster by name | +| cluster update | Update a cluster by name | +| cluster upgrade | Upgrade a cluster by name | +| cluster delete | Delete a cluster by name | +| cluster login | Set a default cluster | +| cluster logout | Unset default cluster | +| cluster kubeconfig | Fetch the kubeconfig for a cluster | +| cluster kubectl | Fetch kubeconfig and run kubectl against it | +| cluster nodepool list | List nodepools in the specified cluster | +| cluster nodepool create | Create a new nodepool in the cluster | +| cluster nodepool delete | Delete a nodepool by name from the cluster | +| cache clear | Clear cache | +| cache kubeconfigs | List cached kubeconfigs | +| quotas | Get quotas | +| fullhelp | Display detailed help information for all commands | +| version | Show the current CLI version | +| install-completion | Install shell completion scripts | + +--- + +### Examples + +```bash +# List all projects +oks-cli project list + +# Dry run project creation +oks-cli project create --project-name my-project --description "Test project" --dry-run + +# Dry run cluster creation +oks-cli cluster create \ + --cluster-name my-cluster \ + --project-name my-project \ + --description "My test cluster" \ + --version "1.32" \ + --dry-run + +# Set a default project profile +oks-cli project login --project-name my-project +``` \ No newline at end of file diff --git a/docs/install.md b/docs/install.md new file mode 100644 index 0000000..0f79fa7 --- /dev/null +++ b/docs/install.md @@ -0,0 +1,21 @@ +## ✅ Requirements + +* Python 3.11 or later +* `pip` (Python package manager) +* `kubectl` (required for commands that interact with the Kubernetes API) + +## 📦 Installation + +### Standard Installation + +```bash +# Create and activate a virtual environment +python -m venv venv +source venv/bin/activate + +# Install the CLI +pip install oks-cli + +# Check version of oks-cli +oks-cli version +``` diff --git a/docs/links.md b/docs/links.md new file mode 100644 index 0000000..7d7f6f7 --- /dev/null +++ b/docs/links.md @@ -0,0 +1,5 @@ +## 🌐 Links + +* 📘 [OKS-CLI Documentation](https://docs.outscale.com/fr/userguide/Installer-et-configurer-OKS-CLI.html) +* 📘 [OKS API Reference](https://docs.outscale.com/oks.html) +* 🐛 [GitHub Issues](https://github.com/outscale/oks-cli/issues) diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..e2bacd8 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,20 @@ +site_name: oks-cli +site_description: A command line to manage Kubernetes clusters on top of OUTSCALE infrastructure +site_author: OUTSCALE +copyright: OUTSCALE +nav: + - Home: index.md + - Installation: install.md + - Commands: commands.md + - Contributing: contributing.md + - Links: links.md + +theme: + name: material +strict: true +markdown_extensions: + - attr_list + - mkdocs-click + +plugins: + - search