[PR-23724][FE] Add some fancy theme

.circleci/config.yml

@@ -6,10 +6,12 @@ executors:
       - auth:
           username: $DOCKERHUB_USERNAME
           password: $DOCKERHUB_ACCESS_TOKEN
-        image: cimg/python:3.12
+        image: cimg/python:3.13
+        environment:
+          ENVIRONMENT: production
 
 orbs:
-  python: circleci/python@2.1.1
+  python: circleci/python@3.0.0
 
 jobs:
   build:
@@ -18,21 +20,15 @@ jobs:
     steps:
       - checkout
 
-      - python/install-packages:
-          app-dir: ~/project
+      - python/install-packages
 
       - run:
           name: Build documentation
-          command: sphinx-build -nW -b html -d build/doctrees source build/html
+          command: sphinx-build -nW -b dirhtml -d build/doctrees source build/html
 
 workflows:
   workflow:
     jobs:
       - build:
           context:
             - org-global
-          filters:
-            branches:
-              ignore:
-                - gh-pages
-                - /.*-gh-pages/

.env.template

@@ -0,0 +1,10 @@
+# The port to use to populate the documentation on your local machine or server
+LOCAL_PORT=8080
+
+# Possible values: development, staging, production
+ENVIRONMENT=development
+
+# Base urls used for the canonical urls compilation
+DEVELOPMENT_HOST=localhost
+STAGING_HOST=docs.bastion.talkable.com
+PRODUCTION_HOST=docs.talkable.com

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,9 +1,5 @@
 <!--- Provide a general summary of your changes in the Title above -->
 
-## Demo
-<!--- Please provide a link to a demo -->
-https://deploy-preview-{{id}}--talkable-docs.netlify.app/
-
 ## Related Stories
 <!--- If this pull request is related to JIRA story, please link to the story here -->
 [![](http://proxies.talkable.com/talkable/PR-1234)](https://talkable.atlassian.net/browse/PR-1234)

.gitignore

@@ -1,7 +1,19 @@
-/build
-/.bundle
-Gemfile.lock
-source/_static/test
-.pivotalrc
+# IDE
 .idea
+.vscode
+
+# Local
 *.log
+.env
+
+# Sphinx
+_build
+build
+
+# Python
+.venv
+__pycache__
+
+# Ruby
+.bundle
+Gemfile.lock

Dockerfile

@@ -0,0 +1,14 @@
+FROM python:3.13-alpine3.21
+
+# Install dependencies
+WORKDIR /docs
+ADD requirements.txt /docs
+RUN python3 -m pip install -r requirements.txt
+
+CMD if [ "$ENVIRONMENT" = "development" ]; then \
+        echo "Running Sphinx in Development mode"; \
+        sphinx-autobuild -b dirhtml /docs/source /docs/_build; \
+    else \
+        echo "Running Sphinx in Staging/Production mode"; \
+        sphinx-build -b dirhtml /docs/source /docs/_build; \
+    fi

README-devops.md

@@ -0,0 +1,94 @@
+## Overview
+
+The Talkable documentation stack is a containerized system that uses Docker to simplify deployment and management. It is designed to generate, serve, and manage static documentation across multiple environments, such as staging and production.
+
+## Key Features
+
+1. **Containerized Components**:
+
+   - **Nginx**: Handles HTTP requests, serves static HTML files, manages URL redirection, and dynamically serves environment-specific `robots.txt` files.
+   - **Sphinx Autobuilder**: Generates static HTML files from source documentation and stores them in a persistent volume shared with Nginx.
+
+2. **Environment-Specific Behavior**:
+
+   - Configured via a `.env` file for flexibility.
+   - Supports dynamic environment-specific behavior, such as serving different `robots.txt` files based on the `ENVIRONMENT` variable.
+
+3. **Efficient Architecture**:
+
+   - Deployed on Amazon AWS Virtual Private Servers (VPS) with an AWS load balancer directing user traffic to the appropriate environment.
+   - Sphinx generates content on a persistent volume that Nginx serves directly.
+
+## Deployment Process
+
+### Prerequisites
+
+- Ensure Docker and Docker Compose are installed on the target VPS.
+- Clone the repository containing the stack configuration.
+
+### Steps
+
+1. **Clone the Repository**:
+
+   ```bash
+   git clone [email protected]:talkable/talkable-docs.git
+   ```
+
+2. **Switch to the Appropriate Branch**:
+
+   - Use the `master` branch for production.
+
+     ```bash
+     git checkout master
+     ```
+
+   - Use the `staging` branch for staging.
+
+     ```bash
+     git checkout staging
+     ```
+
+3. **Create and Configure the `.env` File**:
+
+   - Copy `.env.template` to `.env`:
+
+     ```bash
+     cp .env.template .env
+     ```
+
+   - Update the following variables:
+
+     - **`ENVIRONMENT`**: Set to `development`, `staging`, or `production`.
+     - **`LOCAL_PORT`**: Adjust if the default port (`8080`) is already in use.
+     - Leave `_HOST` variables unchanged unless domain names for staging or production servers are updated.
+
+4. **Deploy the Stack**:
+
+   ```bash
+   docker compose up -d --build
+   ```
+
+## Environment-Specific Configuration
+
+### Handling `robots.txt`
+
+- The repository includes separate `robots.txt` files for each environment.
+- The correct file is dynamically selected based on the `ENVIRONMENT` variable and mapped to the container:
+
+  ```yaml
+  volumes:
+    - ./nginx/robots/${ENVIRONMENT}.txt:/var/www/robots.txt
+  ```
+
+- Nginx serves the file at `/var/www/robots.txt` in response to `robots.txt` requests.
+
+## Persistent Data Sharing
+
+- **Static HTML Files**:
+
+  - Generated by Sphinx and stored in a shared volume.
+  - Served by Nginx without regeneration.
+
+- **Volume Management**:
+  - Shared volumes allow seamless access and updates between containers.
+  - Ensures efficient and consistent behavior across environments.

README-maintainer.md

@@ -0,0 +1,162 @@
+# Talkable Documentation Maintenance Routine
+
+This documentation provides instructions for maintaining the Sphinx Builder **framework** used to generate the Talkable Documentation.
+
+It outlines the routine for maintaining the framework and associated workflows.
+
+> [!NOTE]
+> This guide does not cover updating the documentation content. 
+> Refer to [README.md](README.md) for details on updating the Talkable documentation source, which is available at [https://docs.talkable.com/](https://docs.talkable.com/).
+
+## Scope
+
+The maintenance routine includes the following tasks:
+
+- Updating dependencies:
+  - Sphinx and other Python packages
+  - Python container
+- Adding new extensions
+- Introducing Talkable-specific customizations (Python scripts)
+
+## Preparations
+
+1. Clone the documentation repository.
+
+    ```bash
+    git clone [email protected]:talkable/talkable-docs.git
+    cd talkable-docs
+    ```
+
+2. Create a new branch from `master`.
+
+    ```bash
+    git checkout -b new-branch
+    ```
+
+3. Generate a `.env` file from the `.env.template`.
+
+    ```bash
+    cp .env.template .env
+    ```
+
+## Updating Packages
+
+The goal is to update `requirements.txt` with the latest versions of dependencies.
+
+1. Replace `requirements.txt` with the `packages.txt` file.
+
+    ```bash
+    cp packages.txt requirements.txt
+    ```
+
+2. Build the Sphinx container.
+
+    ```bash
+    docker compose up -d --build
+    ```
+
+    This starts the framework and allows you to load the documentation at http://localhost:8080.
+
+    If the documentation fails to load, check the container logs:
+
+    ```bash
+    docker logs -f docs-sphinx-development
+    ```
+
+3. Test and freeze `requirements.txt`.
+
+    Ensure everything works as expected locally. Once confirmed, update `requirements.txt` to include all installed dependencies with their versions.
+
+    Save the dependencies with the following command:
+
+    ```bash
+    docker exec docs-sphinx-development pip freeze > requirements.txt
+    ```
+
+4. Stop the containers.
+
+    Once the documentation is fully functional, stop the containers:
+
+    ```bash
+    docker compose down -v
+    ```
+
+5. Push the updated `requirements.txt` to GitHub.
+
+    Commit and push the updated `requirements.txt` for testing and production.
+
+## Updating the Python Container
+
+The Sphinx framework uses a Python Docker image from DockerHub.
+
+1. Check for the latest Python image on DockerHub: https://hub.docker.com/_/python.
+
+2. Update the image name in the [Dockerfile](./Dockerfile):
+
+    ```dockerfile
+    FROM python:3.13-alpine3.21
+    ```
+
+3. Test the deployment.
+
+    Deploy the Sphinx container to verify the updates:
+
+    ```bash
+    docker compose up -d --build
+    ```
+
+    Confirm that the documentation loads at http://localhost:8080.
+
+4. Finalize the update.
+
+    Commit the updated `Dockerfile` to the repository for testing and production.
+
+    Stop the containers:
+
+    ```bash
+    docker compose down -v
+    ```
+
+## Adding New Extensions
+
+Sphinx is a highly customizable documentation framework. You can extend its functionality with official or third-party extensions.
+
+Here are some resources:
+
+- https://sphinx-extensions.readthedocs.io/en/latest/
+- https://www.sphinx-doc.org/en/master/development/index.html
+- https://github.com/sphinx-contrib
+
+To add extensions, follow these steps:
+
+1. [Install additional Python packages](#installing-additional-packages).
+2. [Adjust the conf.py file](#modifying-configuration-files).
+3. Add Python scripts to the [./source/](./source/) directory if necessary.
+
+Start by deploying the framework container:
+
+```bash
+docker compose up -d --build
+```
+
+### Installing Additional Packages
+
+Add the package to `requirements.txt`.
+
+Append the package name to `requirements.txt` (version specification is optional at this stage).
+
+> [!NOTE]
+> Version pinning can be done later.
+
+Rebuild the container after modifying `requirements.txt`:
+
+```bash
+docker compose up -d --build
+```
+
+### Modifying Configuration Files
+
+Most changes involve editing the [./source/conf.py](./source/conf.py) file or other files in the [./source/](./source/) directory.
+
+> [!NOTE]
+> Rebuilding the container is unnecessary for changes to [./source/conf.py](./source/conf.py) or [./source/](./source/). These changes are applied automatically within 1 second.