Add docs deployment and version docs

.github/workflows/deploy-docs.yml

@@ -0,0 +1,49 @@
+name: Deploy Documentation
+
+on:
+  workflow_call:
+    inputs:
+      version:
+        required: true
+        type: string
+
+jobs:
+  deploy-docs:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.8"
+      - name: Install dependencies
+        run: pip install .[docs]
+      - name: Configure Git user
+        run: |
+          git config --global user.name "GitHub Actions"
+          git config --global user.email "[email protected]"
+      - name: Remove previous patch versions
+        if: ${{ inputs.version != 'dev' }}
+        run: |
+          # if a 0.1.3 is released we want to remove 0.1.2 from docs and only have the latest patch
+          MAJOR_MINOR=$(echo "${{ inputs.version }}" | cut -d. -f1,2)  # extract `X.Y` from `X.Y.Z`
+          OLD_VERSIONS=$(mike list | grep "^$MAJOR_MINOR" | cut -d' ' -f1 || true)
+          echo "OLD_VERSIONS: $OLD_VERSIONS"
+          for OLD in $OLD_VERSIONS; do
+            if [ "$OLD" != "${{ inputs.version }}" ]; then
+              echo "Removing old patch version: $OLD"
+              mike delete --push "$OLD"
+            fi
+          done
+      - name: Deploy Documentation
+        run: |
+          if [ "${{ inputs.version }}" == "dev" ]; then
+            mike deploy --push --update-aliases dev
+          else
+            mike deploy --push --update-aliases ${{ inputs.version }} latest
+            mike set-default latest --push
+          fi

.github/workflows/main.yml

@@ -136,3 +136,11 @@ jobs:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: |
           gh release create "v${{ env.VERSION }}" --draft --title "v${{ env.VERSION }}" --generate-notes
+
+  deploy-dev-docs:
+    needs: releaseDraft
+    uses: ./.github/workflows/deploy-docs.yml
+    with:
+      version: dev
+    permissions:
+      contents: write

.github/workflows/release.yml

@@ -30,3 +30,12 @@ jobs:
       #     TWINE_USERNAME: __token__
       #     TWINE_PASSWORD: ${{ secrets.PYPI_TOKEN }}
       #   run: twine upload dist/*
+
+  deploy-docs:
+    name: Deploy Documentation
+    needs: publish
+    uses: ./.github/workflows/deploy-docs.yml
+    with:
+      version: ${{ github.event.release.tag_name }}
+    permissions:
+      contents: write

docs/index.md

@@ -1,48 +1,202 @@
-**tome** is a powerful script management tool designed to streamline the organization and
-distribution of scripts across different environments. Built with flexibility and ease of
-use in mind, **tome** enhances the way scripts of any kind are managed, shared, tested,
-and maintained.
+# > tome 📖
 
-Using **tome**, you will benefit from:
+A powerful script management tool.
 
-- **Organization** 📂: Effortlessly manage and structure your scripts for a clean,
-  maintainable codebase.
-- **Collaboration** 🤝: Seamlessly share and collaborate on scripts with your team to
-  enhance productivity.
-- **Testing** 🧪: Ensure your scripts' reliability and performance with comprehensive
-  testing tools.
-- **Maintenance** 🔧: Simplify script upkeep and enhance security with robust maintenance
-  features.
+## Key Features
 
-## Installation
+- Organize 📂: Effortlessly manage and structure your scripts for a clean, maintainable codebase.
+- Collaborate 🤝: Seamlessly share and collaborate on scripts with your team to enhance productivity.
+- Test 🧪: Ensure your scripts' reliability and performance with comprehensive testing tools.
+- Secure 🔒: Manage and protect your passwords using the tome vaults.
 
-The recommended way to install **tome** is using `pip` within a virtual environment. This
-ensures that your project dependencies are isolated and managed effectively:
+## Getting Started
 
-1. Create a virtual environment:
+Install `tome` using pip:
 
+```bash
+$ pip install tome
+```
+
+We highly recommend to [install into a virtual environment](./install.md).
+
+## Using tome
+
+### Installing scripts
+
+You can install scripts from various sources like a git repository, local file or folder,
+zip file (local or http), or requirements file.
+
+For example, you can install the examples from the **tome** repository by doing:
+
+```bash
+$ tome install https://github.com/jfrog/tome.git --folder=examples
+```
+
+!!! note
+
+    Use the ``--folder`` argument when you have your scripts under a subfolder instead the root of the repository
+
+
+### Listing Available Scripts
+
+To list all installed scripts:
+
+```bash
+$ tome list
+
+🚀 ci commands
+ ci:check-pipeline-status       Check the status of a pipeline in the CI.
+ ci:view-logs                   View build or deploy logs from the CI system.
+
+☸️  k8s commands
+ k8s:deploy                     Deploy a Kubernetes resource using a manifest.
+ k8s:get-pods                   List all running pods in a Kubernetes cluster.
+
+📡 server commands
+ server:check-health            Perform a health check on a server.
+ server:log-watch               Stream live logs from a server.
+ server:restart                 Restart a specific server instance.
+ server:scale-down              Decrease the number of server instances.
+ server:scale-up                Increase the number of server instances.
+```
+
+### Running a Script
+
+Execute a script invoking it with ``<namespace>:<command>`` like:
+
+```bash
+$ tome ci:check-pipeline-status --pipeline-id 427
+
+🚀 Checking the status of pipeline #427...
+Fetching pipeline details...
+Pipeline ID: 427
+Project: web-app-deployment
+Status: Running
+Started at: 2025-02-03 18:04:43 UTC
+Duration: 11 minutes
+📄 View pipeline details
+📝 Latest commit: Fix login issue (commit hash: a1b2c3d4)
+[2025-02-03 18:05:43.563673] - Cloning repository...
+[2025-02-03 18:06:58.563673] - Running tests...
+[2025-02-03 18:10:13.563673] - Building Docker image...
+Pipeline still running...
+```
+
+## Creating and Managing Scripts
+
+### Creating a New Script
+
+Create a new script with a predefined structure as a starting point using:
+
+```bash
+$ tome new <namespace>:<command>
+```
+
+Example:
+
+```bash
+$ tome new greetings:hello
 ```
-python -m venv myenv
+
+To start using it, you can install this tome command as editable so that you can see the
+changes while you are developing.
+
+```bash
+$ tome install . -e
 ```
 
-2. Activate the virtual environment:
+The command will appear marked as editable: ``(e)`` if you do a ``tome list``:
 
-=== "UNIX/macOS"
+```bash
+$ tome list
 
-    ```
-    source myenv/bin/activate
-    ```
+...
+🌲 greetings commands
+ greetings:hello (e)            Description of the command.
+...
 
-=== "Windows"
+```
 
-    ```
-    myenv\Scripts\activate
-    ```
+You can open the ``./greetings/hello.py`` file with the editor of your choice and start
+making changes. The changes will be inmediately applied when you are doing them because we
+have installed it as [editable](./editables.md).
 
-Install **tome** using `pip`:
+This command will create something simillar to this file structure:
 
 ```bash
-pip install tomescripts
+.
+└── greetings
+    ├── hello.py
+    └── tests
+        └── test_hello.py
 ```
 
-Now you can start using **tome**
+Let's check the ``hello.py`` file:
+
+```python
+import os
+
+from tome.command import tome_command
+from tome.api.output import TomeOutput
+
+def format_message_hello(message):
+    """
+    Add exclamations for a message
+    """
+    return message + "!!!"
+
+
+@tome_command()
+def hello(tome_api, parser, *args):
+    """
+    Description of the command.
+    """
+    parser.add_argument('positional_argument', help="Placeholder for a positional argument")
+    parser.add_argument('--optional-argument', help="Placeholder for an optional argument")
+    args = parser.parse_args(*args)
+
+    # Add your command implementation here
+    tome_output = TomeOutput()
+    tome_output.info(format_message_hello(f"Tome command called with positional argument: {args.positional_argument}"))
+    if args.optional_argument:
+       tome_output.info(format_message_hello(f"Tome command called with optional argument: {args.optional_argument}"))
+```
+
+For more details on the tome commands syntax please check [reference section](./reference.md).
+
+## Testing Scripts
+
+Tome supports testing using the ``tome test`` command. If you check the files that tome
+new created you will see a tests folder with a ``test_hello.py`` file inside. To run those
+tests just run:
+
+```bash
+$ tome test greetings:hello
+```
+
+To run tests over all installed commands:
+
+```bash
+$ tome test *
+```
+
+!!! note
+
+    ``tome test`` command uses [pytest](https://docs.pytest.org/en/stable/) under the hood, please install it by doing ``pip install pytest``
+
+For more information about testing your scripts with tome please check the [testing commands](./testing.md) section.
+
+## Contributions
+
+We welcome contributions! If you'd like to contribute, please check out our [Contributing
+Guide](https://github.com/jfrog/tome/blob/main/CONTRIBUTING.md) for guidelines. Fork the
+repository, make your changes, and submit a pull request.
+
+If you encounter any issues or have suggestions, feel free to [open an
+issue](https://github.com/jfrog/tome/issues).
+
+## License
+
+Tome is licensed under the [Apache License
+2.0](https://github.com/jfrog/tome/blob/main/LICENSE). See the LICENSE file for full
+details.

docs/install.md

@@ -0,0 +1,34 @@
+## Installation
+
+TODO: install editable, from sources...
+
+The recommended way to install **tome** is using `pip` within a virtual environment. This
+ensures that your project dependencies are isolated and managed effectively:
+
+1. Create a virtual environment:
+
+```
+python -m venv myenv
+```
+
+2. Activate the virtual environment:
+
+=== "UNIX/macOS"
+
+    ```
+    source myenv/bin/activate
+    ```
+
+=== "Windows"
+
+    ```
+    myenv\Scripts\activate
+    ```
+
+Install **tome** using `pip`:
+
+```bash
+pip install tomescripts
+```
+
+Now you can start using **tome**

docs/stylesheets/tome.css

@@ -11,6 +11,8 @@
 
   --content-h1-color-light: #121826;
   --content-h1-color-dark: #ffffff;
+
+  --md-link-color: magenta;
 }
 
 /* Active nav link color */
@@ -66,11 +68,27 @@
   color: var(--content-h1-color-dark);
 }
 
+[data-md-color-scheme="default"] .md-content h2,
+[data-md-color-scheme="default"] .md-content h3 {
+  color: var(--content-h1-color-light);
+}
+
+[data-md-color-scheme="slate"] .md-content h2,
+[data-md-color-scheme="slate"] .md-content h3 {
+  color: var(--content-h1-color-dark);
+}
+
+.md-content a {
+  color: var(--md-link-color);
+  text-decoration: none;
+  font-weight: normal;
+}
+
 .tabbed-content .tabbed-block p {
-    margin: 0;
+  margin: 0;
 }
 
 .tabbed-content .tabbed-block code {
-    display: block;
-    padding: 1em;
+  display: block;
+  padding: 1em;
 }