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,71 @@
+# Welcome to **tome**
+
 **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.
+use in mind, **tome** enhances how scripts of any kind are managed, shared, tested, and
+maintained.
+
+## Why Use **tome**?
+
+With **tome**, you gain:
 
-Using **tome**, you will benefit from:
+- **Organization** 📂: Keep your scripts neatly structured for easy management and
+  maintenance.
+- **Collaboration** 🤝: Seamlessly share scripts with your team, improving productivity.
+- **Testing** 🧪: Ensure script reliability with built-in testing tools.
+- **Security** 🔐: Use **tome vaults** to manage secrets securely.
 
-- **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.
+---
 
 ## Installation
 
 The recommended way to install **tome** is using `pip` within a virtual environment. This
-ensures that your project dependencies are isolated and managed effectively:
+keeps your project dependencies isolated and manageable.
 
-1. Create a virtual environment:
+### 1. Create a Virtual Environment
 
-```
-python -m venv myenv
+```bash
+python -m venv tome-env
 ```
 
-2. Activate the virtual environment:
+### 2. Activate the Virtual Environment
 
-=== "UNIX/macOS"
+#### On UNIX/macOS
 
-    ```
-    source myenv/bin/activate
-    ```
+```bash
+source tome-env/bin/activate
+```
 
-=== "Windows"
+#### On Windows
 
-    ```
-    myenv\Scripts\activate
-    ```
+```bash
+tome-env\Scripts\activate
+```
 
-Install **tome** using `pip`:
+### 3. Install **tome**
+
+Once the virtual environment is activated, install **tome** with:
 
 ```bash
 pip install tomescripts
 ```
 
-Now you can start using **tome**
+---
+
+## Getting Started
+
+Now that **tome** is installed, you can verify the installation by running:
+
+```bash
+tome --help
+```
+
+This will display the available commands and usage options.
+
+For a quick start, try listing all available commands:
+
+```bash
+tome list
+```
+
+To learn more about specific commands, check out the [Usage Guide](use_tome.md).

mkdocs.yml

@@ -1,5 +1,5 @@
 site_name: ">tome"
-
+site_url: "https://jfrog.github.io/tome/"
 nav:
   - Introduction: index.md
   - "Using tome scripts": use_tome.md
@@ -30,6 +30,13 @@ theme:
 
 plugins:
   - mkdocstrings
+  - mike
+
+extra:
+  version:
+    provider: mike
+    alias: true
+    default: latest
 
 extra_css:
   - stylesheets/tome.css

pyproject.toml

@@ -46,7 +46,7 @@ dev = [
     "bandit",
 ]
 
-docs = ["mkdocs", "mkdocstrings[python]", "mkdocs-material"]
+docs = ["mkdocs", "mkdocstrings[python]", "mkdocs-material", "mike"]
 
 [project.scripts]
 tome = "tome.cli:main"