Merge pull request #115 from vintasoftware/feat/better-docs

Several docs improvements

.github/workflows/ci.yml

@@ -27,6 +27,10 @@ jobs:
           pip install poetry
           poetry install
 
+      - name: Check docs build
+        run: |
+          poetry run mkdocs build
+
       - name: Run tests
         run: |
           poetry run coverage run -m pytest
@@ -42,8 +46,8 @@ jobs:
           flag-name: django-coverage
           allow-empty: true
 
-  build-node:
-    name: Node CI
+  build-frontend:
+    name: Frontend CI
     runs-on: ubuntu-latest
     # Wait for Django to finish before starting due to Coveralls parallel
     # Source: https://docs.coveralls.io/parallel-builds
@@ -88,7 +92,7 @@ jobs:
 
   finish:
     name: Coveralls
-    needs: [build-django, build-node]
+    needs: [build-django, build-frontend]
     if: ${{ always() }}
     runs-on: ubuntu-latest
     steps:

.github/workflows/docs-update.yml

@@ -0,0 +1,65 @@
+name: Publish Documentation
+
+on:
+  push:
+    branches:
+      - main
+      - docs-update
+    tags:
+      - '**'
+
+env:
+  COLUMNS: 150
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+
+    steps:
+      - name: checkout docs-site
+        uses: actions/checkout@v4
+        with:
+          ref: docs-site
+
+      - name: checkout current branch
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install poetry
+          poetry install
+
+      - name: Check docs build
+        run: |
+          poetry run mkdocs build
+
+      - name: Run tests
+        run: |
+          poetry run pytest
+        env:
+          OPENAI_API_KEY: "sk-fake-test-key-123"
+
+      - name: Set git credentials
+        run: |
+          git config --global user.name "${{ github.actor }}"
+          git config --global user.email "${{ github.actor }}@users.noreply.github.com"
+
+      - run: poetry run mike deploy -b docs-site dev --push
+        if: "github.ref == 'refs/heads/main'"
+
+      - if: "github.ref == 'refs/heads/docs-update' || startsWith(github.ref, 'refs/tags/')"
+        id: check-version
+        uses: samuelcolvin/[email protected]
+        with:
+          version_file_path: 'django_ai_assistant/__init__.py'
+          skip_env_check: true
+
+      - run: poetry run mike deploy -b docs-site ${{ steps.check-version.outputs.VERSION_MAJOR_MINOR }} latest --update-aliases --push
+        if: "(github.ref == 'refs/heads/docs-update' || startsWith(github.ref, 'refs/tags/')) && !fromJSON(steps.check-version.outputs.IS_PRERELEASE)"

CONTRIBUTING.md

@@ -1,5 +1,9 @@
 # Contributing
 
+We can always use your help to improve Django AI Assistant! Please feel free to tackle existing [issues](https://github.com/vintasoftware/django-ai-assistant/issues). If you have a new idea, please create a thread on [Discussions](https://github.com/vintasoftware/django-ai-assistant/discussions).
+
+Please follow this guide to learn more about how to develop and test the project locally, before opening a pull request.
+
 ## Local Dev Setup
 
 ### Clone the repo

README.md

@@ -1,5 +1,4 @@
-[![Django CI](https://github.com/vintasoftware/django-ai-assistant/actions/workflows/django.yml/badge.svg)](https://github.com/vintasoftware/django-ai-assistant/actions/workflows/django.yml)
-[![Node CI](https://github.com/vintasoftware/django-ai-assistant/actions/workflows/node.yml/badge.svg)](https://github.com/vintasoftware/django-ai-assistant/actions/workflows/node.yml)
+[![CI](https://github.com/vintasoftware/django-ai-assistant/actions/workflows/ci.yml/badge.svg)](https://github.com/vintasoftware/django-ai-assistant/actions/workflows/ci.yml)
 [![Coverage Status](https://coveralls.io/repos/github/vintasoftware/django-ai-assistant/badge.svg?branch=main)](https://coveralls.io/github/vintasoftware/django-ai-assistant?branch=main)
 
 # django-ai-assistant ![docs/images/robot-happy-outline.svg]
@@ -15,12 +14,12 @@ Please check the documentation: [https://vintasoftware.github.io/django-ai-assis
 
 ## Contributing
 
-You're welcome to contribute with Django AI Assistant! Please feel free to tackle existing [issues](https://github.com/vintasoftware/django-ai-assistant/issues). If you have a new idea, please open a new issue to discuss it.
+You're welcome to contribute with Django AI Assistant! Please feel free to tackle existing [issues](https://github.com/vintasoftware/django-ai-assistant/issues). If you have a new idea, please create a thread on [Discussions](https://github.com/vintasoftware/django-ai-assistant/discussions). 
 
 Check our [contributing guide](CONTRIBUTING.md) to learn more about how to develop and test the project locally, before opening a pull request.
 
 ## Commercial Support
 
 [![alt text](https://avatars2.githubusercontent.com/u/5529080?s=80&v=4 "Vinta Logo")](https://www.vintasoftware.com/)
 
-This is an open-source project maintained by [Vinta Software](https://www.vinta.com.br/) and is used in products of Vinta's clients. We are always looking for exciting work! If you need any commercial support, feel free to get in touch: [email protected]
+This is an open-source project maintained by [Vinta Software](https://www.vinta.com.br/). We are always looking for exciting work! If you need any commercial support, feel free to get in touch: [email protected]

django_ai_assistant/__init__.py

@@ -14,5 +14,5 @@
 )
 
 
-version = __version__ = metadata.version(__package__)
-package_name = __package__
+PACKAGE_NAME = __package__ or "django-ai-assistant"
+VERSION = __version__ = metadata.version(PACKAGE_NAME)

django_ai_assistant/api/views.py

@@ -8,7 +8,7 @@
 from ninja.operation import Operation
 from ninja.security import django_auth
 
-from django_ai_assistant import package_name, version
+from django_ai_assistant import PACKAGE_NAME, VERSION
 from django_ai_assistant.api.schemas import (
     AssistantSchema,
     ThreadMessagesSchemaIn,
@@ -26,13 +26,13 @@ class API(NinjaAPI):
     # Force "operationId" to be like "django_ai_assistant_delete_thread"
     def get_openapi_operation_id(self, operation: Operation) -> str:
         name = operation.view_func.__name__
-        return (package_name + "_" + name).replace(".", "_")
+        return (PACKAGE_NAME + "_" + name).replace(".", "_")
 
 
 def init_api():
     return API(
-        title=package_name,
-        version=version,
+        title=PACKAGE_NAME,
+        version=VERSION,
         urls_namespace="django_ai_assistant",
         # Add auth to all endpoints
         auth=django_auth,

docs/get-started.md

@@ -1,3 +1,8 @@
+---
+search:
+  boost: 2 
+---
+
 # Get started
 
 ## Prerequisites

docs/reference/index.md

@@ -0,0 +1,9 @@
+# Reference
+
+This is the reference documentation for the Django AI Assistant library.
+
+## Modules
+
+- [django_ai_assistant.helpers.use_cases](use-cases-ref.md)
+- [django_ai_assistant.helpers.assistants](assistants-ref.md)
+- [django_ai_assistant.models](models-ref.md)

docs/support.md

@@ -0,0 +1,11 @@
+# Support
+
+If you have any questions or need help, feel free to create a thread on [GitHub Discussions](https://github.com/vintasoftware/django-ai-assistant/discussions).
+
+In case you're facing a bug, please [check existing issues](https://github.com/vintasoftware/django-ai-assistant/issues) and create a new one if needed.
+
+## Commercial Support
+
+[![alt text](https://avatars2.githubusercontent.com/u/5529080?s=80&v=4 "Vinta Logo")](https://www.vintasoftware.com/)
+
+This is an open-source project maintained by [Vinta Software](https://www.vinta.com.br/). We are always looking for exciting work! If you need any commercial support, feel free to get in touch: [email protected]

docs/tutorial.md

@@ -1,3 +1,8 @@
+---
+search:
+  boost: 2 
+---
+
 # Tutorial
 
 In this tutorial, you will learn how to use Django AI Assistant to supercharge your Django project with LLM capabilities.
@@ -215,7 +220,7 @@ assistant.run("What's the weather in New York City?", thread_id=thread.id)
 messages = get_thread_messages(thread=thread, user=user)  # returns both user and AI messages
 ```
 
-More CRUD helpers are available at `django_ai_assistant.use_cases` module. Check the [Reference](use-cases-ref.md) for more information.
+More CRUD helpers are available at `django_ai_assistant.use_cases` module. Check the [Reference](reference/use-cases-ref.md) for more information.
 
 ### Using built-in API views
 
@@ -403,4 +408,4 @@ shows an example of a RAG-powered AI Assistant that's able to answer questions a
 
 ### Further configuration of AI Assistants
 
-You can further configure the `AIAssistant` subclasses by overriding its public methods. Check the [Reference](assistants-ref.md) for more information.
+You can further configure the `AIAssistant` subclasses by overriding its public methods. Check the [Reference](reference/assistants-ref.md) for more information.

mkdocs.yml

@@ -1,17 +1,29 @@
 site_name: django-ai-assistant
 site_description: Implement powerful AI assistants using Django
+site_url: https://vintasoftware.github.io/django-ai-assistant/
 
 repo_name: vintasoftware/django-ai-assistant
 repo_url: https://github.com/vintasoftware/django-ai-assistant/
 edit_uri: blob/main/docs/
 
+copyright: From <a href="https://www.vintasoftware.com">Vinta Software</a> to the community with 💙
+
 theme:
   name: material
   icon:
     logo: material/robot-happy-outline
   favicon: images/robot-happy-outline.svg
   features:
+    - navigation.footer
+    - navigation.indexes
+    - navigation.sections
     - navigation.tabs
+    - navigation.top
+    - navigation.tracking
+    - search.highlight
+    - search.share
+    - search.suggest
+    - toc.follow
   palette:
     # Palette toggle for automatic mode
     - media: "(prefers-color-scheme)"
@@ -33,8 +45,6 @@ theme:
         icon: material/brightness-4
         name: Switch to system preference
 
-copyright: <a href="https://www.vintasoftware.com">Vinta Software</a>
-
 markdown_extensions:
   - admonition
   - pymdownx.highlight:
@@ -55,12 +65,15 @@ nav:
   - Get Started: get-started.md
   - Tutorial: tutorial.md
   - Reference:
-    - helpers.assistants: assistants-ref.md
-    - helpers.use_cases: use-cases-ref.md
-    - models: models-ref.md
+    - reference/index.md
+    - helpers.use_cases: reference/use-cases-ref.md
+    - helpers.assistants: reference/assistants-ref.md
+    - models: reference/models-ref.md
   - Contributing: contributing.md
+  - Support: support.md
 
 plugins:
+  - search
   - mkdocstrings:
       handlers:
         python:
@@ -71,3 +84,17 @@ plugins:
             show_symbol_type_toc: true
             members_order: source
             modernize_annotations: true
+
+extra:
+  social:
+    - icon: fontawesome/brands/github
+      link: https://github.com/vintasoftware/django-ai-assistant/
+      name: Django AI Assistant GitHub
+    - icon: fontawesome/brands/x-twitter
+      link: https://x.com/vintasoftware
+      name: Vinta Software X
+    - icon: fontawesome/brands/linkedin
+      link: https://linkedin.com/company/vintasoftware
+      name: Vinta Software LinkedIn
+  version:
+    provider: mike