diff --git a/.circleci/config.yml b/.circleci/config.yml index 72d4b3d46..ba6254a5c 100644 --- a/.circleci/config.yml +++ b/.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,12 +20,11 @@ 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: @@ -31,8 +32,3 @@ workflows: - build: context: - org-global - filters: - branches: - ignore: - - gh-pages - - /.*-gh-pages/ diff --git a/.env.template b/.env.template new file mode 100644 index 000000000..4bfe1792a --- /dev/null +++ b/.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 diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 5d752ddc8..cca63a8aa 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,9 +1,5 @@ -## Demo - -https://deploy-preview-{{id}}--talkable-docs.netlify.app/ - ## Related Stories [![](http://proxies.talkable.com/talkable/PR-1234)](https://talkable.atlassian.net/browse/PR-1234) diff --git a/.gitignore b/.gitignore index 14ec1a9a3..9dd6b0384 100644 --- a/.gitignore +++ b/.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 \ No newline at end of file diff --git a/.ruby-gemset b/.ruby-gemset deleted file mode 100644 index 10b85f5b3..000000000 --- a/.ruby-gemset +++ /dev/null @@ -1 +0,0 @@ -talkable-docs diff --git a/.ruby-version b/.ruby-version deleted file mode 100644 index 47b322c97..000000000 --- a/.ruby-version +++ /dev/null @@ -1 +0,0 @@ -3.4.1 diff --git a/CNAME b/CNAME deleted file mode 100644 index fe80f6e25..000000000 --- a/CNAME +++ /dev/null @@ -1 +0,0 @@ -docs.talkable.com diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 000000000..5dba08b0b --- /dev/null +++ b/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 diff --git a/Gemfile b/Gemfile deleted file mode 100644 index 11fcd5bc1..000000000 --- a/Gemfile +++ /dev/null @@ -1,11 +0,0 @@ -source 'https://rubygems.org' - -ruby file: '.ruby-version' - -gem 'base64' # Removed from standard library in Ruby 3.4 -gem 'foreman' -gem 'guard-livereload' -gem 'guard-shell' -gem 'rake' -gem 'reline' # Removed from standard library in Ruby 3.5 -gem 'webrick' diff --git a/Guardfile b/Guardfile deleted file mode 100644 index dfe8ecf09..000000000 --- a/Guardfile +++ /dev/null @@ -1,14 +0,0 @@ -guard 'shell' do - watch(%r{(.*)\.rst}) do |m| - system("sphinx-build -b html -d build/doctrees source build/html") - end - - watch(%r{^source/_static/}) do |m| - system("rsync -az source/_static build/html") - end -end - -guard 'livereload' do - watch(%r{(.*)\.rst}) - watch(%r{^source/_static/}) -end diff --git a/Procfile b/Procfile deleted file mode 100644 index 2da95c518..000000000 --- a/Procfile +++ /dev/null @@ -1,2 +0,0 @@ -web: ruby -run -e httpd -- --port=5001 build/html -guard: bundle exec guard diff --git a/README-devops.md b/README-devops.md new file mode 100644 index 000000000..6d6d3563d --- /dev/null +++ b/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 git@github.com: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. diff --git a/README-maintainer.md b/README-maintainer.md new file mode 100644 index 000000000..524c9e2bf --- /dev/null +++ b/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 git@github.com: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. diff --git a/README.md b/README.md index 6f23ceb9c..217926c72 100644 --- a/README.md +++ b/README.md @@ -1,30 +1,84 @@ -Talkable Documentation -====================== +## What is Talkable Documentation? -[![Build Status](https://circleci.com/gh/talkable/talkable-docs.svg?style=svg&circle-token=cc33458158e7b0c1f6f8cbf1bcbf74f00ee28a8e)](https://circleci.com/gh/talkable/workflows/talkable-docs) +The set of articles describing Talkable's capabilities, publicly available at [docs.talkable.com](https://docs.talkable.com). -This GitHub repository represents Talkable’s documentation site, located at [docs.talkable.com](https://docs.talkable.com). +It uses [reStructuredText](https://docutils.sourceforge.io/rst.html) as its markup language, an easy-to-read, what-you-see-is-what-you-get plaintext markup syntax. All reStructuredText formatting capabilities can be found in [The reST Quickref](https://docutils.sourceforge.io/docs/user/rst/quickref.html). -The Talkable documentation uses [reStructuredText](https://docutils.sourceforge.io/rst.html) as its markup language and is built using [Sphinx](https://www.sphinx-doc.org). +It is built using [Sphinx](https://www.sphinx-doc.org), an open-source documentation generation tool that transforms plain text files into beautifully formatted documentation. For more details, see [The Sphinx Documentation](https://www.sphinx-doc.org). -Sphinx ------- +## Where is it stored? -For more details see [The Sphinx Documentation](https://www.sphinx-doc.org). +It's stored in a dedicated GitHub repository ([talkable-docs](https://github.com/talkable/talkable-docs)). -reStructuredText ----------------- +The repository consists of the following branches: -For more details see [The reST Quickref](https://docutils.sourceforge.io/docs/user/rst/quickref.html). +- [master](https://github.com/talkable/talkable-docs/tree/master): The main branch used to keep the most recent stable version available at [docs.talkable.com](https://docs.talkable.com). +- [staging](https://github.com/talkable/talkable-docs/tree/staging): A staging branch used for testing by QA. It is available at [docs.bastion.talkable.com](https://docs.bastion.talkable.com). +- Feature branches created from `master` by individual contributors/developers. + +## What is the documentation update workflow? + +1. Pull changes from `master`. +2. Checkout a new branch from `master`. +3. Deploy the local/development environment. +4. Make changes and test them locally. +5. Commit the changes to the `staging` branch. +6. Get the documentation tested by QA. +7. Create a pull request to the `master` branch, providing the staging URL of the changed page in the pull request description. +8. Merge the pull request once it passes the review. + +## How to deploy the local environment? + +0. **Install Docker** + + Follow the [official Docker documentation](https://docs.docker.com/compose/install/). + +1. **Navigate to the repository root directory.** + + Ensure the `docker-compose.yml` file is located there. + +2. **Create an `.env` file by copying `.env.template`.** + + Review and update the variable values if needed. + + For a **development/local environment**, all default settings should work out of the box. The only value you may need to change is `LOCAL_PORT` if `8080` is already in use on your local machine. + +3. **Run the local environment deployment.** + + Run the command: + + ```bash + docker compose up -d --build + ``` + + If everything is set up correctly, the documentation will be available at [http://localhost:8080](http://localhost:8080). Make sure you use the port number defined in the `.env` file. + + If the documentation does not load, check the **Troubleshooting** section. + +## How to deploy changes to production and staging? + +You should not deploy it manually! + +The deployment is handled by [Jenkins job](http://jenkins.production/view/Talkable-docs/). + +All you need to do is commit your changes to the corresponding branch to deploy them to the appropriate server: +- Commit to the [staging](https://github.com/talkable/talkable-docs/tree/staging) branch => [docs.bastion.talkable.com](https://docs.bastion.talkable.com/). +- Commit to the [master](https://github.com/talkable/talkable-docs/tree/master) branch => [docs.talkable.com](https://docs.talkable.com/). + +## How do I make the actual changes? + +Navigate to the [source](./source/) directory and update the files using `reStructuredText` syntax. Refer to [The reST Quickref](https://docutils.sourceforge.io/docs/user/rst/quickref.html) for syntax details. + +Here are some formatting examples: ### Sections Section headings are very flexible in reST. We use the following convention in the Talkable documentation: -* `#` for module headings -* `=` for sections -* `-` for subsections -* `.` for subsubsections +- `#` for module headings +- `=` for sections +- `-` for subsections +- `.` for subsubsections ### Cross-referencing @@ -57,79 +111,22 @@ Here is a reference to "talkable section": :ref:`talkable-section` which will ha name "Talkable Section". ``` -Build the documentation ------------------------ - -First install [Sphinx](https://www.sphinx-doc.org). See below. - -### Installing Sphinx on macOS - -* Install [Homebrew](https://brew.sh). - -* Install Ruby and [Bundler](https://bundler.io), and run `bundle install` to install dependencies. - -* Install Python (>= 3.9) and pip: - - ``` - brew install python - ``` - - More information in case of trouble: https://docs.brew.sh/Homebrew-and-Python - -* Install dependencies: - - ``` - pip3 install -r requirements.txt --break-system-package - ``` - - If you have problems, try adding `-I` flag (`--ignore-installed`) to the `pip install` command. - -If you get the error "unknown locale: UTF-8" when generating the documentation, -the solution is to define the following environment variables: - - export LANG=en_US.UTF-8 - export LC_ALL=en_US.UTF-8 - -### Building - -Run `rake preview` from "master" branch. - -#### Setting up LiveReload - -Run `rake server` from "master" branch and open `http://localhost:5000` in browser. - -### Deploying - -If you’re deploying for the first time make sure you have `gh-pages` branch locally. Otherwise run the following command to create it: `git checkout -b gh-pages origin/gh-pages`. - -General flow: -1. Pull changes from master -2. Checkout your new branch from master -3. Make changes -4. Deploy your changes to staging (see the instruction below) -4. Create a Pull Request to "master" branch, providing the demo URL to the changed page in Pull Request’s description. -5. Merge pull request once it passes the review -6. Deploy - -If you did everything right, deploying is as easy as `rake deploy` from "master" branch. - -#### Deploying to Staging +## Troubleshooting -If it’s your first time deploying to staging, run `rake setup` to setup git remote. +#### Can't view the documentation locally in the browser? -1. Switch to local branch "void" and pull the latest changes from the remote: - `git checkout void; git pull` -2. Merge your branch into local branch "void": - `git merge YOUR_BRANCH_NAME` -3. Push the changes to the remote branch "void": - ```git push origin void``` -4. Deploy: - ```rake deploy:staging``` +1. Ensure you are using the correct port number and protocol. + The port number should match the value provided in `.env` as `LOCAL_PORT`. ---- +2. Check logs: -See "master" branch: https://github.com/talkable/talkable-docs + ```bash + docker logs -f docs-sphinx-development + ``` -See "gh-pages" branch: https://github.com/talkable/talkable-docs/tree/gh-pages +## Links -See GitHub Page (auto generated): https://docs.talkable.com +- GitHub "staging" branch: [staging](https://github.com/talkable/talkable-docs/tree/staging) +- Staging web server: [docs.bastion.talkable.com](https://docs.bastion.talkable.com/) +- GitHub "production" branch: [master](https://github.com/talkable/talkable-docs/tree/master) +- Production web server: [docs.talkable.com](https://docs.talkable.com/) diff --git a/Rakefile b/Rakefile deleted file mode 100644 index f47ca6c00..000000000 --- a/Rakefile +++ /dev/null @@ -1,109 +0,0 @@ -# frozen_string_literal: true -require 'mkmf' - -SPHINX_BUILD = ENV['SPHINX_BUILD'] || 'sphinx-build' -SOURCE_DIR = 'source' -BUILD_DIR = 'build' -SPHINX_OPTS = "-b html -d #{BUILD_DIR}/doctrees #{SOURCE_DIR} #{BUILD_DIR}/html" - -task :default => :help -task :help do - system 'rake --tasks' -end - -desc 'Set up deploys' -task :setup do - sh 'git remote add staging git@github.com:talkable/void-talkable-docs.git' -end - -task :environment do - ENV['LANG'] = ENV['LC_ALL'] = 'en_US.UTF-8' - find_executable(SPHINX_BUILD) || abort("The '#{SPHINX_BUILD}' command was not found. Make sure you have Sphinx installed, then set the SPHINX_BUILD environment variable to point to the full path of the '#{SPHINX_BUILD}' executable. Alternatively you can add the directory with the executable to your PATH. If you do not have Sphinx installed, grab it from http://sphinx-doc.org/") - - regexp = /(\d+\.)?(\d+\.)?(\*|\d+)/ - required = File.read('requirements.txt').match(regexp).to_s - installed = `#{SPHINX_BUILD} --version`.match(regexp).to_s rescue '' - if !required.empty? && !installed.empty? && Gem::Version.new(required) > Gem::Version.new(installed) - abort "\nYou are running an outdated version of Sphinx #{installed}. Required version is #{required}. Run `pip3 install -r requirements.txt --break-system-packages` to upgrade Sphinx." - end -end - -desc 'Run build in test mode' -task :test => :environment do - sh "#{SPHINX_BUILD} -nW #{SPHINX_OPTS}" -end - -task :build => :environment do - sh "#{SPHINX_BUILD} #{SPHINX_OPTS}" - - Rake::FileList["#{BUILD_DIR}/html/**/*.html"].each do |filename| - File.open(filename, "r+") do |file| - old_content = file.read - new_content = old_content.gsub(%r{ [:clean, :build] - -desc 'Run the server on localhost:5001 and open a browser' -task :server => :preview do - sh '(sleep 2 && open "http://localhost:5001")&' - sh 'bundle exec foreman start' -end - -desc 'Commit and deploy changes to https://docs.talkable.com' -task :deploy => :'deploy:production' - -namespace :deploy do - def deploy(domain:, html_branch:, source_branch:, disallow_robots:, push_command:) - sh "git checkout #{html_branch}" - sh 'git pull' - sh "find . -not -path './.git' -not -path './.git/*' -not -path './Rakefile' -not -path './.circleci' -not -path './.circleci/*' -delete" - sh "git checkout #{source_branch} #{SOURCE_DIR} .gitignore requirements.txt" - sh 'git reset HEAD' - Rake::Task[:build].invoke - sh "(cd #{BUILD_DIR}/html && tar c ./) | (cd ./ && tar xf -)" - sh "rm -rf #{BUILD_DIR} #{SOURCE_DIR} .buildinfo" - File.write('.nojekyll', '') - File.write('CNAME', domain) - File.write('robots.txt', "User-agent: *\nDisallow: /") if disallow_robots - sh 'git add -A' - sh "git commit -m \"Generated gh-pages for `git log #{source_branch} -1 --pretty=short --abbrev-commit`\" && #{push_command} ; git checkout #{source_branch}" - - puts "\nDeployment finished. Check updated docs at https://#{domain}" - end - - task :production do - deploy( - domain: 'docs.talkable.com', - html_branch: 'gh-pages', - source_branch: 'master', - disallow_robots: false, - push_command: 'git push origin gh-pages' - ) - end - - desc 'Commit and deploy changes to https://void-docs.talkable.com' - task :staging do - sh 'git remote show staging' do |ok, _| - Rake::Task[:setup].invoke unless ok - end - - deploy( - domain: 'void-docs.talkable.com', - html_branch: 'void-gh-pages', - source_branch: 'void', - disallow_robots: true, - push_command: 'git push -f origin void-gh-pages && git push -f staging void-gh-pages:gh-pages' - ) - end -end diff --git a/deploy/Jenkinsfile b/deploy/Jenkinsfile new file mode 100644 index 000000000..4f1656ad7 --- /dev/null +++ b/deploy/Jenkinsfile @@ -0,0 +1,86 @@ +#!/usr/bin/env groovy + +pipeline { + agent { + label "staging" + } + environment { + GITHUB_ACC = credentials('talkable-bot-deploy-token') + JENKINS_BUILD_USER_ID = "" + LOCAL_PORT="8080" + } + triggers { + pollSCM('* * * * *') // Polls SCM every minute + } + parameters { + choice(name: "DEPLOY_COMMAND", + choices: ["deploy", "ci_status"], + description: "DEPLOY - Start the default deployment\nCI_STATUS - Check the GitHub commit status on CircleCI") + } + options { + buildDiscarder(logRotator(numToKeepStr: '15', daysToKeepStr: '14')) + disableConcurrentBuilds() + parallelsAlwaysFailFast() + ansiColor('xterm') + } + stages { + stage('Preparation') { + steps { + script { + wrap([$class: 'BuildUser']) { + JENKINS_BUILD_USER_ID = "${BUILD_USER_ID}" + currentBuild.displayName = "${JOB_BASE_NAME}-${BUILD_NUMBER}" + currentBuild.description = "Build by ${JENKINS_BUILD_USER_ID}" + } + if (env.BRANCH_NAME == 'master') { + env.HOST_ENV = '10.200.1.200' + env.JENKINS_CRED_ID = 'ssh-jenkins-to-prod1-wp-nginx' + env.ENVIRONMENT="production" + env.PRODUCTION_HOST="docs.talkable.com" + } else if (env.BRANCH_NAME == 'staging') { + env.HOST_ENV = '10.1.2.12' + env.JENKINS_CRED_ID = 'ssh-jenkins-to-bastion-wp-nginx' + env.ENVIRONMENT="staging" + env.STAGING_HOST="docs.bastion.talkable.com" + } else { + echo "Hello from ${BRANCH_NAME} branch! We only build the following branches of the Talkable repository: master, staging." + error("Non-supported branch for build") + } + } + } + } + stage('Build') { + steps { + script { + withCredentials([sshUserPrivateKey(credentialsId: "${JENKINS_CRED_ID}", keyFileVariable: 'SSH_KEY', usernameVariable: 'SSH_USER')]) { + sh "$WORKSPACE/deploy/deploy.sh ${DEPLOY_COMMAND}" + } + } + } + } + } + post { + success { + echo 'Build was a success' + } + failure { + echo 'Build failed' + } + unstable { + echo 'Build is unstable' + } + aborted { + echo 'Build was aborted' + } + cleanup { + echo 'Performing cleanup' + cleanWs cleanWhenFailure: false, + cleanWhenUnstable: true, + cleanWhenAborted: true, + cleanWhenNotBuilt: true, + cleanWhenSuccess: true, + deleteDirs: true, + notFailBuild: true + } + } +} diff --git a/deploy/deploy.sh b/deploy/deploy.sh new file mode 100755 index 000000000..659f94f00 --- /dev/null +++ b/deploy/deploy.sh @@ -0,0 +1,133 @@ +#!/usr/bin/env bash +set -ex +echo $SECONDS + +echo "=== Environment Variables ===" +printenv | sort + +TIMEFRAME_SECONDS=240 +PROJECT_ROOT="talkable-docs" +SUBPROJECT="docs" +CIRCLE_CI_API_URL="https://api.github.com/repos/talkable/${PROJECT_ROOT}/commits/${GIT_COMMIT}/status" +CIRCLE_CI_URL="https://app.circleci.com/pipelines/github/talkable/${PROJECT_ROOT}?branch=" +TASK=$1 + +#FUNCTIONS +print_help() { + clear + echo 'Available Commands:' + echo ' deploy - deploy current version of talkable' + echo ' ci | cistatus | status - status on CircleCI' + echo 'Example:' + echo ' deploy.sh deploy' + echo ' deploy.sh cistatus' + exit 0 +} + +ci_status() { + show_status() { + curl -s -u "$GITHUB_ACC_USR":"$GITHUB_ACC_PSW" "$CIRCLE_CI_API_URL" | jq -r '.statuses[]' | jq '.context, .state' | grep ci/circleci -A1 + } + + while true; do + local tests_status + tests_status=$(curl -s -u "$GITHUB_ACC_USR":"$GITHUB_ACC_PSW" "$CIRCLE_CI_API_URL" | + jq -e -r ' + [.statuses[].state] as $states | + if ($states | length) == 0 then + "no_tests" + elif $states | all(. == "success") then + "success" + elif $states | any(. == "failure" or . == "error") then + "failure" + elif $states | any(. == "pending") then + "pending" + else + "unknown" + end + ') + + if [[ -z $tests_status ]]; then + echo "Error: Could not retrieve tests statuses. Check API response or credentials." + exit 1 + fi + + if [[ $tests_status == "success" ]]; then + show_status + echo "The sphinx build has succeeded!" + break + elif [[ $tests_status == "failure" ]]; then + show_status + echo -e "The Sphinx build failed on CircleCI.\nCheck the CircleCI results here: $CIRCLE_CI_URL$BRANCH_NAME" + exit 1 + elif [[ $tests_status == "no_tests" ]]; then + show_status + echo -e "There is no sphinx build on CircleCI for the commit.\nCheck the CircleCI results here: $CIRCLE_CI_URL$ENV_BRANCH" + exit 1 + elif [[ $tests_status == "pending" ]]; then + echo "Tests is pending or queued. Waiting for sphinx build ..." + fi + + if [[ $SECONDS -gt $TIMEFRAME_SECONDS ]]; then + show_status + echo -e "The build is marked as FAILURE by timeout.\nCheck the CircleCI results here: $CIRCLE_CI_URL$ENV_BRANCH" + echo "Total elapsed time: $((SECONDS / 60)) minutes" + exit 228 + fi + + echo "Waiting for all tests to succeed. Next check in 8 seconds..." + echo "Elapsed time: $((SECONDS / 60)) minutes. Timeout at $((TIMEFRAME_SECONDS / 60)) minutes." + sleep 8 + done + + echo "CI checks completed successfully." + echo "Total elapsed time: $((SECONDS / 60)) minutes" +} + +remote_ssh_exec() { + ssh -o StrictHostKeyChecking=no -i "$SSH_KEY" "$SSH_USER@$HOST_ENV" "$@" +} + +deploy_docs() { + remote_ssh_exec < /path/ + # e.g. /index.html => / + rewrite "^/(.*)index\.html$" /$1 permanent; + + # Otherwise remove ".html" and append slash + # e.g. /overview.html => /overview/ + rewrite "^/(.+)\.html$" /$1/ permanent; + } + + # Serve static assets with long cache + location ~* \.(?:css|js|jpe?g|png|gif|ico|svg|woff2?|ttf|eot|otf|webp)$ { + expires 1y; + add_header Cache-Control "public, max-age=31536000, immutable"; + access_log off; + try_files $uri =404; + } + + # Redirect requests starting with /search/?q=& to / + # Fix of the Furo theme bug described here https://talkable.atlassian.net/browse/PR-23789 + # location /search/ { + # if ($arg_q = "") { + # return 301 /; + # } + # } + + # Serve robots.txt from a specific file + location = /robots.txt { + alias /var/www/robots.txt; + access_log off; + log_not_found off; + } + + # Default static-file behavior + location / { + try_files $uri $uri/ =404; + } +} diff --git a/robots.txt b/nginx/robots/development.txt similarity index 53% rename from robots.txt rename to nginx/robots/development.txt index 60ed3d057..1f53798bb 100644 --- a/robots.txt +++ b/nginx/robots/development.txt @@ -1,3 +1,2 @@ User-agent: * -Disallow: - +Disallow: / diff --git a/source/robots.txt b/nginx/robots/production.txt similarity index 87% rename from source/robots.txt rename to nginx/robots/production.txt index f3fc00670..4acb8d432 100644 --- a/source/robots.txt +++ b/nginx/robots/production.txt @@ -1,3 +1,4 @@ User-agent: * +Allow: / Sitemap: https://docs.talkable.com/sitemap.xml diff --git a/nginx/robots/staging.txt b/nginx/robots/staging.txt new file mode 100644 index 000000000..45813aeac --- /dev/null +++ b/nginx/robots/staging.txt @@ -0,0 +1,4 @@ +User-agent: * +Disallow: / + +Sitemap: https://docs.bastion.talkable.com/sitemap.xml diff --git a/packages.txt b/packages.txt new file mode 100644 index 000000000..470254163 --- /dev/null +++ b/packages.txt @@ -0,0 +1,9 @@ +# This is a list of packages used in the framework +# Used by the documentation maintainer +# Add the package name here if you add some to the framework + +sphinx-copybutton +sphinx-sitemap +sphinx-autobuild +sphinx-book-theme +sphinx-design diff --git a/requirements.txt b/requirements.txt index afee09fd6..59857e703 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,2 +1,43 @@ +accessible-pygments==0.0.5 +alabaster==1.0.0 +anyio==4.8.0 +babel==2.16.0 +beautifulsoup4==4.12.3 +certifi==2024.12.14 +charset-normalizer==3.4.1 +click==8.1.8 +colorama==0.4.6 +docutils==0.21.2 +furo==2024.8.6 +h11==0.14.0 +idna==3.10 +imagesize==1.4.1 +Jinja2==3.1.5 +MarkupSafe==3.0.2 +packaging==24.2 +pydata-sphinx-theme==0.16.1 +Pygments==2.19.1 +requests==2.32.3 +sniffio==1.3.1 +snowballstemmer==2.2.0 +soupsieve==2.6 Sphinx==8.1.3 +sphinx-autobuild==2024.10.3 +sphinx-basic-ng==1.0.0b2 +sphinx-book-theme==1.1.3 +sphinx-copybutton==0.5.2 +sphinx-favicon==1.0.1 sphinx-sitemap==2.6.0 +sphinx_design==0.6.1 +sphinxcontrib-applehelp==2.0.0 +sphinxcontrib-devhelp==2.0.0 +sphinxcontrib-htmlhelp==2.1.0 +sphinxcontrib-jsmath==1.0.1 +sphinxcontrib-qthelp==2.0.0 +sphinxcontrib-serializinghtml==2.0.0 +starlette==0.45.3 +typing_extensions==4.12.2 +urllib3==2.3.0 +uvicorn==0.34.0 +watchfiles==1.0.4 +websockets==14.2 diff --git a/source/_static/talkable.css b/source/_static/talkable.css index 47296eb48..396ab24e7 100644 --- a/source/_static/talkable.css +++ b/source/_static/talkable.css @@ -1,695 +1,43 @@ -@import url("basic.css"); -@import url(https://fonts.googleapis.com/css?family=Roboto:400,500,700,300,400italic); - -/* -- page layout ----------------------------------------------------------- */ -html { - background-color: #EDF0F3; - min-height: 100%; -} - -body { - font: 300 16px/1.45 "Roboto", sans-serif; - color: #3e4f6c; - margin: 0; - padding: 0; -} - -div.admonition, -div.topic, -blockquote, -pre, div[class*="highlight-"] { - clear: none; -} - -div.sidebar::after, -div.topic::after, -div.admonition::after, -blockquote::after, -div.section::after { - clear: none; -} - -.clearfix { - *zoom: 1; -} - -.clearfix:before, -.clearfix:after { - display: table; - content: ""; -} - -.clearfix:after { - clear: both; -} - -.content-container { - margin: auto; - max-width: 960px; - box-sizing: border-box; -} - -a, .a, a:visited { - color: #D36835; - cursor: pointer; - text-decoration: none; -} - -.current > a, -a.current, -a:hover { - color: #3e4f6c; -} - -abbr { - letter-spacing: 0.08em; -} - -.inline { - display: inline-block; -} - -.button { - background: #f0632f; - border: 1px solid #c04f26; - border-radius: 4px; - color: #fff; - cursor: pointer; - display: inline-block; - font: 300 14px/normal "Roboto", sans-serif; - padding: 8px 15px 9px; -} - -.button:hover, -.button:focus { - background-color: #db5523; -} - -.button:active { - background-color: #cb4616; -} - -.textfield { - border: 2px solid #c5cbd4; - border-radius: 4px; - font: 300 14px/normal "Roboto", sans-serif; - height: 36px; - padding: 9px 10px; - width: 100%; - -moz-box-sizing: border-box; - -webkit-box-sizing: border-box; - box-sizing: border-box; - transition: border-color .25s; -} - -.textfield::-moz-placeholder { - color: #ddd; -} - -.textfield::-webkit-input-placeholder { - color: #ddd; -} - -.textfield:focus { - border-color: #90a1b5; -} - -.bodywrapper { - background-color: #fff; - border-radius: 6px; - margin-left: 243px; - margin-bottom: 60px; -} - -.bodywrapper ol, -.bodywrapper ul { - margin-left: 0; - padding-left: 23px; -} - -.bodywrapper blockquote { - margin: 0; -} - -.body { - line-height: 1.5; - padding: 22px 30px 30px; -} - -.body img { - border: 1px solid #ddd; - border-radius: 4px; - box-shadow: 0 5px 15px rgba(0, 0, 0, .2); -} - -.body img.is-minimal { - border: none; - border-radius: 0; - box-shadow: none; - margin: 20px 0; -} - -.nav { - float: left; - line-height: 1.35; - padding: 27px 20px 40px 0; - width: 243px; -} - -.nav ul { - list-style-type: none; - margin: 0; - padding: 0; -} - -.nav li { - margin-bottom: 5px; -} - -.nav ul ul { - font-size: 14px; - margin: 5px 0 5px 20px; -} - -.nav ul ul.simple { - margin-bottom: 0; - margin-top: 0; -} - -/* SEARCH FORM */ -.search-form { - display: inline-block; - vertical-align: middle; - width: 50%; -} - -.search-form-field { - margin-right: 1%; - width: 75%; -} - -/* HEADER */ -.header { - margin: 0 auto; - max-width: 960px; - padding: 20px 0; -} - -.header .button { - width: 23%; -} - -.header-disclaimer { - float: right; - padding-top: 9px; -} - -.header-logo { - background: url("img/logo.svg") no-repeat; - color: transparent; - display: inline-block; - font-size: 0; - height: 32px; - margin-right: 50px; - text-indent: -99999em; - vertical-align: middle; - width: 189px; - background-size: 100%; -} - -blockquote.epigraph { - display: inline-block; - zoom: 1; - margin: 0 -30px 0 -30px; - padding: 30px 70px; - background: #FFE9CE; +.sidebar-logo { + margin: 0; } table.docutils { - width: 100%; + box-shadow: none; + width: 100%; } -table.docutils th, table.docutils td { - border-bottom: 2px solid #e0e0e0; - padding: 8px 8px 8px 0px; - vertical-align: top; -} - -.ptable table { - width: 100%; - margin: 1em 0 1em 0; -} - -.ptable table tr td:first-child, -.ptable table tr th:first-child { - width: 20%; -} - -/* -- body styles ----------------------------------------------------------- */ -p { - margin: 0.8em 0 0.5em 0; -} - -h1, h2, h3, h4, h5, h6 { - font-weight: 200; -} - -h1 { - font-size: 250%; - margin: 0; - padding: 0 0 0.3em 0; - line-height: 1.2em; -} - -h2 { - font-size: 200%; - margin: 1.3em 0 0.2em 0; - padding: 0 0 10px 0; -} - -h3 { - font-size: 160%; - margin: 1em 0 -0.3em 0; - padding-bottom: 5px; -} - -h4 { - font-size: 140%; - margin: 1em 0 -0.3em 0; - padding-bottom: 5px; -} - -div.body h1 a, -div.body h2 a, -div.body h3 a, -div.body h4 a, -div.body h5 a, -div.body h6 a { - color: #657B83 !important; - font-size: 16px; - margin-left: 10px; - vertical-align: middle; -} - -h1 a.anchor, -h2 a.anchor, -h3 a.anchor, -h4 a.anchor, -h5 a.anchor, -h6 a.anchor { - display: none; - margin: 0 0 0 0.3em; - padding: 0 0.2em 0 0.2em; - color: #aaa !important; -} - -h1:hover a.anchor, -h2:hover a.anchor, -h3:hover a.anchor, -h4:hover a.anchor, -h5:hover a.anchor, -h6:hover a.anchor { - display: inline; -} - -h1 a.anchor:hover, -h2 a.anchor:hover, -h3 a.anchor:hover, -h4 a.anchor:hover, -h5 a.anchor:hover, -h6 a.anchor:hover { - color: #777; - background-color: #eee; -} - -cite, code, tt { - font-family: 'Source Code Pro', monospace; - font-size: 0.9em; - letter-spacing: 0.01em; - background-color: #FFF9DA; - font-style: normal; - word-break: break-all; -} - -hr { - border: 1px solid #eee; - margin: 2em 0; -} - -.highlight { - border-left: 4px solid #DADADA; - background: none !important; -} - -pre { - font-family: 'Source Code Pro', monospace; - font-style: normal; - font-size: 14px; - line-height: 1.4; - padding: 15px 20px; - white-space: pre-wrap; /* css-3 */ - white-space: -moz-pre-wrap; /* Mozilla, since 1999 */ - white-space: -pre-wrap; /* Opera 4-6 */ - white-space: -o-pre-wrap; /* Opera 7 */ - word-wrap: break-word; /* Internet Explorer 5.5+ */ -} - -pre a { - color: inherit; - text-decoration: underline; -} - -td.linenos pre { - padding: 0.5em 0; -} - -div.quotebar { - background-color: #f8f8f8; - max-width: 250px; - float: right; - padding: 2px 7px; - border: 1px solid #ccc; -} - -div.topic { - background-color: #f8f8f8; -} - -table { - border-collapse: collapse; - margin: 0; -} - -table td, table th { - padding: 0.2em 0.5em 0.2em 0.5em; + vertical-align: top; + padding: 1px 16px 24px 5px; } -div.admonition { - border-left: 4px solid #D36835; - margin: 2em 0; - padding: 15px 20px; +body[data-theme="light"] .highlight, +body[data-theme="light"] .highlight button.copybtn, +body[data-theme="light"] .highlight button.copybtn.success:after { + background: #f2f2f2 !important; } -div.admonition p { - margin: 0.5em 0; -} - -div.admonition pre { - margin: 0.4em 0; -} - -div.admonition p.admonition-title { - color: #D36835; - margin: 0 0 5px; - font-weight: bold; -} - -div.warning, -div.important { - border-left-color: red; -} - -div.warning p.admonition-title, -div.important p.admonition-title { - color: red; -} - -div.hint, -div.tip { - border-left-color: #3e4f6c; -} - -div.hint p.admonition-title, -div.tip p.admonition-title { - color: #3e4f6c; -} - -div.caution, -div.attention, -div.danger, -div.error { - border-left-color: #dc322f; -} - -div.caution p.admonition-title, -div.attention p.admonition-title, -div.danger p.admonition-title, -div.error p.admonition-title { - color: #dc322f; -} - -div.admonition ul, div.admonition ol { - margin: 0.1em 0.5em 0.5em 3em; - padding: 0; -} - -div.versioninfo { - margin: 1em 0 0 0; - border: 1px solid #eee; - background-color: #ddeaf0; - padding: 8px; - line-height: 1.3em; - font-size: 0.9em; -} - -div.viewcode-block:target { - background-color: #f4debf; - border-top: 1px solid #eee; - border-bottom: 1px solid #eee; -} - -ol > li { - margin-top: 15px; -} - -ol > li:first-child { - margin-top: 0; -} - -.reference.internal em { - font-style: normal; -} - -div.hidden { - display: none; -} - -.underline { - text-decoration: underline; -} - -.mtn, .mvn, .man { - margin-top: 0px; -} - -.mrn, .mhn, .man { - margin-right: 0px; -} - -.mbn, .mvn, .man { - margin-bottom: 0px; -} - -.mln, .mhn, .man { - margin-left: 0px; -} - -.mtx, .mvx, .max { - margin-top: 3px; -} - -.mrx, .mhx, .max { - margin-right: 3px; -} - -.mbx, .mvx, .max { - margin-bottom: 3px; -} - -.mlx, .mhx, .max { - margin-left: 3px; -} - -.mts, .mvs, .mas { - margin-top: 5px; -} - -.mrs, .mhs, .mas { - margin-right: 5px; -} - -.mbs, .mvs, .mas { - margin-bottom: 5px; -} - -.mls, .mhs, .mas { - margin-left: 5px; -} - -.mtm, .mvm, .mam { - margin-top: 10px; -} - -.mrm, .mhm, .mam { - margin-right: 10px; -} - -.mbm, .mvm, .mam { - margin-bottom: 10px; -} - -.mlm, .mhm, .mam { - margin-left: 10px; -} - -.mtl, .mvl, .mal { - margin-top: 20px; -} - -.mrl, .mhl, .mal { - margin-right: 20px; -} - -.mbl, .mvl, .mal { - margin-bottom: 20px; -} - -.mll, .mhl, .mal { - margin-left: 20px; -} - -.mtxl, .mvxl, .maxl { - margin-top: 30px; -} - -.mrxl, .mhxl, .maxl { - margin-right: 30px; -} - -.mbxl, .mvxl, .maxl { - margin-bottom: 30px; -} - -.mlxl, .mhxl, .maxl { - margin-left: 30px; -} - -.mtxxl, .mvxxl, .maxxl { - margin-top: 40px; -} - -.mrxxl, .mhxxl, .maxxl { - margin-right: 40px; +@media (prefers-color-scheme: light) { + body[data-theme="auto"] .highlight, + body[data-theme="auto"] .highlight button.copybtn, + body[data-theme="auto"] .highlight button.copybtn.success:after { + background: #f2f2f2 !important; + } } -.mbxxl, .mvxxl, .maxxl { - margin-bottom: 40px; +.highlight button.copybtn:hover { + stroke: var(--color-link); } -.mlxxl, .mhxxl, .maxxl { - margin-left: 40px; +.headerlink { + visibility: hidden !important; } -.page-break-after, -.header-printable { +.hidden { display: none; } -/* FIREFOX SPECIFIC */ -@-moz-document url-prefix() { - .button { - padding-bottom: 8px; - padding-top: 6px; - } -} - -/* MQ */ -@media only screen and (max-width: 980px) { - .header { - padding-left: 20px; - padding-right: 20px; - } - - .header-disclaimer { - font-size: 80%; - } - - .content-container { - padding: 0 20px; - } -} - -@media only print { - html { - background-color: transparent; - } - - .nav, - .search-form { - display: none !important; - } - - .header { - padding-top: 0; - margin-bottom: 40px; - } - - .header-logo { - background-image: none; - } - - .header-logo:after { - content: url(img/logo.svg); - } - - .section li { - position: relative; - page-break-inside: avoid; - } - - .admonition { - position: relative; - page-break-inside: avoid; - page-break-before: avoid; - } - - .section, - .section li { - widows: 2; - orphans: 2; - } - - .body h1, - .body h2, - .body h3, - .body h4, - .body h5, - .body h6 { - display: block; - position: relative; - page-break-after: avoid; - } - - .body h1 { - text-align: center; - } - - .body img { - display: block; - position: relative; - page-break-before: avoid; - max-height: 700px; - margin: 20px 0; - } - - .body p { - font-size: 20px; - } - - .page-break-after { - display: block; - position: relative; - page-break-after: always; - } +dd { + margin-inline-start: 20px; } diff --git a/source/_templates/layout.html b/source/_templates/layout.html index 781745852..4acdccc34 100644 --- a/source/_templates/layout.html +++ b/source/_templates/layout.html @@ -1,49 +1,16 @@ -{% extends "basic/layout.html" %} -{% block relbar1 %}{% endblock %} -{% block relbar2 %}{% endblock %} -{% block sidebarlogo %}{% endblock %} -{% block sidebar2 %}{% endblock %} +{% extends "!layout.html" %} -{%- block doctype -%} - -{%- endblock -%} - -{%- block extrahead -%} - - - -{%- endblock -%} - -{# put the sidebar before the body #} -{%- block sidebar1 %} - {% block rootrellink %} -
- - {%- block sidebarsearch %} - {%- if pagename != "search" and builder != "singlehtml" %} -
- - - - -
- {%- endif %} - {%- endblock %} -
- Visit - www.talkable.com -
-
- {% endblock %} - -
- {%- block sidebartoc %} -
- {{ toctree(maxdepth=3) }} -
- {%- endblock %} +{# Set the title and sitename divider to '|' and hide 'no title' if the page has no title #} +{% block htmltitle %} + {% if title == "<no title>" %} + {{ docstitle|e }} + {% else %} + {{ title|striptags|e }} | {{ docstitle|e }} + {% endif %} {% endblock %} +{# Google Tag Manager injection #} + {%- block footer %}
- -{%- endblock %} -{% block extrahead %} - - {{ super() }} -{% endblock %} -{% block body %} -

{{ _('Search') }}

- {% block scriptwarning %} - - {% endblock %} - {% block searchtext %} -

- {% trans %}Searching for multiple words only shows matches that contain - all words.{% endtrans %} -

- {% endblock %} - {% block searchbox %} -
- - - -
- {% endblock %} - {% block searchresults %} - {% if search_performed %} -

{{ _('Search Results') }}

- {% if not search_results %} -

{{ _('Your search did not match any documents. Please make sure that all words are spelled correctly and that you\'ve selected enough categories.') }}

- {% endif %} - {% endif %} -
- {% if search_results %} -
    - {% for href, caption, context in search_results %} -
  • {{ caption }} -
    {{ context|e }}
    -
    • - {% endfor %} -
- {% endif %} -
- {% endblock %} -{% endblock %} diff --git a/source/_utils/__init__.py b/source/_utils/__init__.py new file mode 100644 index 000000000..5712dd70e --- /dev/null +++ b/source/_utils/__init__.py @@ -0,0 +1 @@ +from .baseurl import baseurl diff --git a/source/_utils/baseurl.py b/source/_utils/baseurl.py new file mode 100644 index 000000000..d15df347d --- /dev/null +++ b/source/_utils/baseurl.py @@ -0,0 +1,15 @@ +import os + +local_port = os.getenv("LOCAL_PORT") +environment = os.getenv("ENVIRONMENT") +production_host = os.getenv("PRODUCTION_HOST") +staging_host = os.getenv("STAGING_HOST") +development_host = os.getenv("DEVELOPMENT_HOST") + +baseurl_json = { + "development": f"http://{development_host}:{local_port}/", + "staging": f"https://{staging_host}/", + "production": f"https://{production_host}/", +} + +baseurl = baseurl_json.get(environment) diff --git a/source/advanced_features/converting_into_localization.rst b/source/advanced_features/converting_into_localization.rst index 25e586161..9547b2084 100644 --- a/source/advanced_features/converting_into_localization.rst +++ b/source/advanced_features/converting_into_localization.rst @@ -11,49 +11,49 @@ If you don’t know what is Localization inside Talkable :ref:`read this article Few benefits you get out of using Localizations: - 1. It is extremely easy to set up an AB test if your copy is coded up as a Localization. - 2. For non-technical people it is easier to change the copy inside Localization Editor because they are afraid to code. +- It is extremely easy to set up an AB test if your copy is coded up as a Localization. +- For non-technical people it is easier to change the copy inside Localization Editor because they are afraid to code. 1. Visit Campaign Editor: -.. image:: /_static/img/advanced_features/campaign_navigation.png + .. image:: /_static/img/advanced_features/campaign_navigation.png 2. Swith to HTML & CSS editor: -.. image:: /_static/img/advanced_features/campaign_navigation_html_css_editor.png + .. image:: /_static/img/advanced_features/campaign_navigation_html_css_editor.png 3. Find a View you would like to convert a static copy at: -.. image:: /_static/img/advanced_features/campaign_view_navigation.png + .. image:: /_static/img/advanced_features/campaign_view_navigation.png 4. Find a copy that you’d like to convert into a Localization. You can hit `Cmd+F` (`Ctrl+F` on Windows) to search within HTML area. -Static copy is basically a piece of text that sits inside HTML & CSS Editor and usually looks like this: + Static copy is basically a piece of text that sits inside HTML & CSS Editor and usually looks like this: -.. code-block:: html + .. code-block:: html -

- Get {{ advocate_incentive.description }}. -

+

+ Get {{ advocate_incentive.description }}. +

-A piece that we are going to extract into Localizations is just a copy, without HTML tags. To do that, simply wrap the text into a variable notation like so: + A piece that we are going to extract into Localizations is just a copy, without HTML tags. To do that, simply wrap the text into a variable notation like so: -.. code-block:: html + .. code-block:: html -

- {{ "advocate_share_page_headline" | localize: "Get [[ advocate_incentive.description ]]." }} -

+

+ {{ "advocate_share_page_headline" | localize: "Get [[ advocate_incentive.description ]]." }} +

5. Go back to Editor to see newly created Localization: -.. image:: /_static/img/advanced_features/campaign_localization_sidebar.png + .. image:: /_static/img/advanced_features/campaign_localization_sidebar.png .. raw:: html

Few important things to remember

-1. Don’t forget to change `{{` into `[[` inside interpolation variables, otherwise variables will lose its function and become just a plain text. -2. Keep in mind that `identifier` ("advocate_share_page_headline" in the example above) is a campaign-level Localization in fact, always remember to provide unique names for them, otherwise you will be overriding a value of one Localization. +- Don’t forget to change `{{` into `[[` inside interpolation variables, otherwise variables will lose its function and become just a plain text. +- Keep in mind that `identifier` ("advocate_share_page_headline" in the example above) is a campaign-level Localization in fact, always remember to provide unique names for them, otherwise you will be overriding a value of one Localization. .. warning:: @@ -66,23 +66,23 @@ It is highly unlikely that your campaign is not equipped with Subject line as a Subject line is unique because its default value is set on the Advocate Signup/Share Page along with other email sharing fields (email body, reminder checkbox value), not Friend Share email as it might sounded logical. Here is the plan: - 1. Create Subject Line as a Localization on the Advocate Signup/Share Page, provide its default value, it will be used inside `value` attribute of the "subject" form field: +1. Create Subject Line as a Localization on the Advocate Signup/Share Page, provide its default value, it will be used inside `value` attribute of the "subject" form field: - .. image:: /_static/img/advanced_features/subject_line_setup_inside_share_page.png + .. image:: /_static/img/advanced_features/subject_line_setup_inside_share_page.png - .. code-block:: html + .. code-block:: html - This code creates new Localization named "Friend share email subject" that you are able to change on the Advocate Signup/Share Page. + This code creates new Localization named "Friend share email subject" that you are able to change on the Advocate Signup/Share Page. - 2. Navigate to Friend Share email → Extra fields to see Email Subject field: +2. Navigate to Friend Share email → Extra fields to see Email Subject field: - .. image:: /_static/img/advanced_features/campaign_editor_subject.png + .. image:: /_static/img/advanced_features/campaign_editor_subject.png - 3. Put the following code in there: +3. Put the following code in there: - .. code-block:: liquid + .. code-block:: liquid {% if custom_message_subject == blank %} {{ 'friend_share_email_subject' | localize }} @@ -90,54 +90,54 @@ Subject line is unique because its default value is set on the Advocate Signup/S {{ custom_message_subject }} {% endif %} - The code snippet above checks if the Advocate provided any Subject at all. If not we take default Subject copy so Friend Share email does not come with a blank subject. + The code snippet above checks if the Advocate provided any Subject at all. If not we take default Subject copy so Friend Share email does not come with a blank subject. Color As Localization --------------------- Another example would be localizing font color of a headline, all copy at once, or a background color of a button. You can use `color` trait of a Localization for that. - 1. Navigate to HTML & CSS editor of the View you want to add a color Localization on: +1. Navigate to HTML & CSS editor of the View you want to add a color Localization on: - .. image:: /_static/img/advanced_features/campaign_navigation_html_css_editor.png + .. image:: /_static/img/advanced_features/campaign_navigation_html_css_editor.png - 2. At the very bottom of the HTML area add ```` tag with CSS that will override default styling of the element you want to localize: +2. At the very bottom of the HTML area add ```` tag with CSS that will override default styling of the element you want to localize: - .. code-block:: text + .. code-block:: text .button { background-color: {{ "advocate_share_page_button_color" | localize: "#f94d08", trait: "color" }}; border-color: {{ "advocate_share_page_button_color" | localize: "#f94d08", trait: "color" }}; } - In the code example above we created new Color Localization with default HEX color `#f94d08` which is used for `background-color` and `border-color` CSS properties of `.button` selector. Whenever you set a new color inside Campaign Editor it will be changed across both places because we’re using the same Localization identifier in both places. + In the code example above we created new Color Localization with default HEX color `#f94d08` which is used for `background-color` and `border-color` CSS properties of `.button` selector. Whenever you set a new color inside Campaign Editor it will be changed across both places because we’re using the same Localization identifier in both places. - 3. New Color Localization appears under "Color" tab inside Campaign Editor: +3. New Color Localization appears under "Color" tab inside Campaign Editor: - .. image:: /_static/img/advanced_features/editor_colors_tab.png + .. image:: /_static/img/advanced_features/editor_colors_tab.png Image As Localization --------------------- Localizing Image asset can be handy if you want to AB test it. Here is how to do that: - 1. Navigate to HTML & CSS editor of the View you want to add a color Localization on: +1. Navigate to HTML & CSS editor of the View you want to add a color Localization on: - .. image:: /_static/img/advanced_features/campaign_navigation_html_css_editor.png + .. image:: /_static/img/advanced_features/campaign_navigation_html_css_editor.png - 2. Inside HTML area find an image you want to localize. An image can be either within CSS or within HTML area (``, inline styles, etc.). If the image is set within CSS you need to extract it into HTML area using inline styles: +2. Inside HTML area find an image you want to localize. An image can be either within CSS or within HTML area (``, inline styles, etc.). If the image is set within CSS you need to extract it into HTML area using inline styles: - .. code-block:: text + .. code-block:: text
...
- In the example above `share_page_background` is a name of an Image Localization. `share-page-background.jpg` is a name of an Asset (Files tab within HTML & CSS Editor). + In the example above `share_page_background` is a name of an Image Localization. `share-page-background.jpg` is a name of an Asset (Files tab within HTML & CSS Editor). - 3. Now we can see newly created Image Localization under "Images" tab: +3. Now we can see newly created Image Localization under "Images" tab: - .. image:: /_static/img/advanced_features/editor_images_tab.png + .. image:: /_static/img/advanced_features/editor_images_tab.png Custom Option (Configuration) Localization ------------------------------------------ @@ -146,33 +146,33 @@ In addition to localizing Images, Colors, and static copy Talkable allows you to An example can be to create an AB test for Equal Emphasis (all 3 sharing channels look visually equal) vs. Email Emphasis where email sharing form stands out: - .. image:: /_static/img/advanced_features/share_page_equal_emphasis.png - :height: 250 px +.. image:: /_static/img/advanced_features/share_page_equal_emphasis.png + :height: 250 px - .. image:: /_static/img/advanced_features/share_page_email_emphasis.png - :height: 250 px +.. image:: /_static/img/advanced_features/share_page_email_emphasis.png + :height: 250 px -In order to chieve this AB test we need to +In order to chieve this AB test we need to: - 1. Build two separate layouts using CSS cascades to style all nested children within a container block that holds all the content: +1. Build two separate layouts using CSS cascades to style all nested children within a container block that holds all the content: - .. code-block:: text + .. code-block:: text {% assign share_page_layout = "share_page_layout" | localize: "Equal Emphasis", "Email Emphasis" %} - The code above creates a local Liquid variable named `share_page_layout` and assigns `share_page_layout` Configuration Localization to it. - Then we optimize the variable value to be set as an HTML `class` attribute (downcase, replace spaces with hyphens) and set it as a part of a `class` attribute. + The code above creates a local Liquid variable named `share_page_layout` and assigns `share_page_layout` Configuration Localization to it. + Then we optimize the variable value to be set as an HTML `class` attribute (downcase, replace spaces with hyphens) and set it as a part of a `class` attribute. - 2. Now inside Campaign Editor we can see newly created Configuration Localization: +2. Now inside Campaign Editor we can see newly created Configuration Localization: - .. image:: /_static/img/advanced_features/editor_configuration_tab.png + .. image:: /_static/img/advanced_features/editor_configuration_tab.png - 3. Let’s switch back to HTML & CSS editor and start applying CSS styling to both layouts. Knowing their final classes inside HTML: `class="container is-equal-emphasis"` and `class="container is-email-emphasis"` we can easily style both layouts inside CSS area like so (SCSS is also allowed and is shown as an example for code simplicity): +3. Let’s switch back to HTML & CSS editor and start applying CSS styling to both layouts. Knowing their final classes inside HTML: `class="container is-equal-emphasis"` and `class="container is-email-emphasis"` we can easily style both layouts inside CSS area like so (SCSS is also allowed and is shown as an example for code simplicity): - .. code-block:: scss + .. code-block:: scss .container { &.is-equal-emphasis { @@ -188,10 +188,6 @@ In order to chieve this AB test we need to } } - All other nested children can be styled following this pattern. + All other nested children can be styled following this pattern. - 4. Once you’re done with styling it is very easy to set up an AB test, just go back to Campaign Editor and click "Add A/B test variant" link. Once a Campaign goes Live it will start rotating both variants following AB test distribution rules (50:50 by default). - -.. container:: hidden - - .. toctree:: +4. Once you’re done with styling it is very easy to set up an AB test, just go back to Campaign Editor and click "Add A/B test variant" link. Once a Campaign goes Live it will start rotating both variants following AB test distribution rules (50:50 by default). diff --git a/source/advanced_features/coupons.rst b/source/advanced_features/coupons.rst index f16c3f50f..94833322d 100644 --- a/source/advanced_features/coupons.rst +++ b/source/advanced_features/coupons.rst @@ -45,10 +45,6 @@ Shopify coupon auto-sync Read :ref:`Shopify coupon auto-sync documentation ` for details. -.. container:: hidden - - .. toctree:: - Requirements ------------ diff --git a/source/advanced_features/customer_service_portal/overview.rst b/source/advanced_features/customer_service_portal/overview.rst index be446365d..e5c94b61e 100644 --- a/source/advanced_features/customer_service_portal/overview.rst +++ b/source/advanced_features/customer_service_portal/overview.rst @@ -31,6 +31,3 @@ Example of Customer Service Portal person lookup: .. image:: /_static/img/advanced_features/customer_service_portal/person_lookup.png -.. container:: hidden - - .. toctree:: diff --git a/source/advanced_features/customer_service_portal/terminology.rst b/source/advanced_features/customer_service_portal/terminology.rst index db831d078..0366d90f8 100644 --- a/source/advanced_features/customer_service_portal/terminology.rst +++ b/source/advanced_features/customer_service_portal/terminology.rst @@ -12,35 +12,35 @@ Advocate’s invite (a share). A referral will not be created unless the followi Friend Email, and a Purchase made by a Referred Friend. Each referral is passed through several fraud checks (configured inside Fraud Settings). As a result of the fraud checks each referral status can be: - 1. **In progress**: Talkable referral engine is processing the referral. Such action usually takes less than a second - so it is highly unlikely that you will see this status. No rewards are issued at this point. - - 2. **Pending**: a referral is pending approval. Talkable referral engine approves pending referrals automatically - with a delay set under fraud settings. A user can also approve a referral manually until the auto-approval happens. - Thus, if the referral fraud checks were passed successfully each referral will eventually become approved. - No rewards are issued up until approval. - - 3. **Flagged**: due to having many different options to configure referral fraud checks, - it is not always possible to set up an automatic resolution for each referral. - For such cases, you may want to Flag referrals that are in a so-called grey area, - where the chance of fraud is around 50% and it is impossible to make the decision automatically. - All flagged referrals are added to a queue and can be accessed inside CSP → Referrals. - No rewards are issued at this point. All flagged referrals will be automatically resolved - to either voided or approved status, depending on the fraud settings configuration. - It is recommended to void flagged referrals automatically so you can only approve valid ones manually. - As a result this can save lots of time as most flagged referrals are rather suspicious than valid. - - 4. **Approved**: this is a valid referral status which either gets set by the Talkable referral engine - or by a user. Flagged referrals can also turn to approved. All rewards associated - with the referral are then passed to the next stage to verify if they - can be issued. - - 5. **Voided**: this status is set by a user manually if they decide a referral is invalid and there should be no - rewards issued as a result. Only pending and flagged referrals can be voided. Talkable referral engine cannot set - this status automatically. All rewards associated with the referral are getting blocked as a result. - - 6. **Blocked**: when some fraud checks are failed Talkable referral engine blocks the referral immediately. All rewards - associated with the referral are getting blocked as a result. +1. **In progress**: Talkable referral engine is processing the referral. Such action usually takes less than a second + so it is highly unlikely that you will see this status. No rewards are issued at this point. + +2. **Pending**: a referral is pending approval. Talkable referral engine approves pending referrals automatically + with a delay set under fraud settings. A user can also approve a referral manually until the auto-approval happens. + Thus, if the referral fraud checks were passed successfully each referral will eventually become approved. + No rewards are issued up until approval. + +3. **Flagged**: due to having many different options to configure referral fraud checks, + it is not always possible to set up an automatic resolution for each referral. + For such cases, you may want to Flag referrals that are in a so-called grey area, + where the chance of fraud is around 50% and it is impossible to make the decision automatically. + All flagged referrals are added to a queue and can be accessed inside CSP → Referrals. + No rewards are issued at this point. All flagged referrals will be automatically resolved + to either voided or approved status, depending on the fraud settings configuration. + It is recommended to void flagged referrals automatically so you can only approve valid ones manually. + As a result this can save lots of time as most flagged referrals are rather suspicious than valid. + +4. **Approved**: this is a valid referral status which either gets set by the Talkable referral engine + or by a user. Flagged referrals can also turn to approved. All rewards associated + with the referral are then passed to the next stage to verify if they + can be issued. + +5. **Voided**: this status is set by a user manually if they decide a referral is invalid and there should be no + rewards issued as a result. Only pending and flagged referrals can be voided. Talkable referral engine cannot set + this status automatically. All rewards associated with the referral are getting blocked as a result. + +6. **Blocked**: when some fraud checks are failed Talkable referral engine blocks the referral immediately. All rewards + associated with the referral are getting blocked as a result. Reward ------ @@ -60,6 +60,3 @@ This is what the person gets as a result of some action (incentive). Available r - **Blocked/No reward**: there was no reward created either because the associated referral was blocked according to Fraud Settings or because of other reasons: incentive criteria has blocked it, or the person was blocklisted. -.. container:: hidden - - .. toctree:: diff --git a/source/advanced_features/customer_service_portal/use_case_1.rst b/source/advanced_features/customer_service_portal/use_case_1.rst index 6bf5173d9..3ca745235 100644 --- a/source/advanced_features/customer_service_portal/use_case_1.rst +++ b/source/advanced_features/customer_service_portal/use_case_1.rst @@ -49,6 +49,3 @@ Let’s also expand fraud filters section to check the details: This looks like a valid referral. Let’s move on to :ref:`Use case #2 `. -.. container:: hidden - - .. toctree:: \ No newline at end of file diff --git a/source/advanced_features/customer_service_portal/use_case_2.rst b/source/advanced_features/customer_service_portal/use_case_2.rst index 0cb4b70f8..583acd934 100644 --- a/source/advanced_features/customer_service_portal/use_case_2.rst +++ b/source/advanced_features/customer_service_portal/use_case_2.rst @@ -60,6 +60,3 @@ Here is what email statuses mean: - **Scheduled**: the email will be sent on a specified date. - **Rejected**: the email was rejected by some reason. -.. container:: hidden - - .. toctree:: \ No newline at end of file diff --git a/source/advanced_features/customer_service_portal/use_case_3.rst b/source/advanced_features/customer_service_portal/use_case_3.rst index 7a0fa6ae7..70a71f63d 100644 --- a/source/advanced_features/customer_service_portal/use_case_3.rst +++ b/source/advanced_features/customer_service_portal/use_case_3.rst @@ -69,12 +69,11 @@ Here is how to detect self-referrals in case you’ve got an email/call from a c 1. Enter the customer’s email address in the Person Lookup. 2. Review the “Referrals” tab and look for a “self-referral” alert: -.. image:: /_static/img/advanced_features/customer_service_portal/self_referral.jpg + .. image:: /_static/img/advanced_features/customer_service_portal/self_referral.jpg -3. Inspect the customer’s email address to see if it’s the same or similar to the Friends; you can also inspect inside -the referral details the IP address and cookie to see if they match: +3. Inspect the customer’s email address to see if it’s the same or similar to the Friends; you can also inspect inside the referral details the IP address and cookie to see if they match: -.. image:: /_static/img/advanced_features/customer_service_portal/fraud_settings.jpg + .. image:: /_static/img/advanced_features/customer_service_portal/fraud_settings.jpg 4. If it’s not obvious why the customer was flagged for self-referral (meaning that none of these three items matched), then you should click “Details” to dive deeper. @@ -84,7 +83,7 @@ the referral details the IP address and cookie to see if they match: share as an Advocate and click on the share link as a Friend), and lastly, there’s a matching combination of IP address and user agent - meaning the Advocate and Friend were using the same device and IP address, in combination. -.. image:: /_static/img/advanced_features/customer_service_portal/blocked_reasons.jpg + .. image:: /_static/img/advanced_features/customer_service_portal/blocked_reasons.jpg Cross referrals --------------- @@ -95,6 +94,3 @@ in an attempt to get both the Advocate and Friend rewards. We identify this in the same way as described above. -.. container:: hidden - - .. toctree:: diff --git a/source/advanced_features/customer_service_portal/use_case_4.rst b/source/advanced_features/customer_service_portal/use_case_4.rst index 1924dec80..59e9f6e31 100644 --- a/source/advanced_features/customer_service_portal/use_case_4.rst +++ b/source/advanced_features/customer_service_portal/use_case_4.rst @@ -52,6 +52,3 @@ flagged/blocked ones. We see that the blocked reason in this case is “Matching .. image:: /_static/img/advanced_features/customer_service_portal/marked_as_fraud.jpg -.. container:: hidden - - .. toctree:: \ No newline at end of file diff --git a/source/advanced_features/customer_service_portal/use_case_5.rst b/source/advanced_features/customer_service_portal/use_case_5.rst index a57d186e8..095513b51 100644 --- a/source/advanced_features/customer_service_portal/use_case_5.rst +++ b/source/advanced_features/customer_service_portal/use_case_5.rst @@ -45,6 +45,3 @@ If you realize that you made a mistake in Blocklisting a user who should actuall all you have to do to take a user off the blocklist is to delete their email or IP from the list and then hit “Save Changes” again. It’s that easy. -.. container:: hidden - - .. toctree:: diff --git a/source/advanced_features/customer_service_portal/use_case_6.rst b/source/advanced_features/customer_service_portal/use_case_6.rst index a79bc0599..f8ed552c1 100644 --- a/source/advanced_features/customer_service_portal/use_case_6.rst +++ b/source/advanced_features/customer_service_portal/use_case_6.rst @@ -51,6 +51,3 @@ After creating the referral manually you will be taken to the newly created refe Advocate reward may be blocked due to incentive criteria, make sure to check the Advocate’s reward status as shown on the screenshot above. -.. container:: hidden - - .. toctree:: \ No newline at end of file diff --git a/source/advanced_features/facebook_login_share.rst b/source/advanced_features/facebook_login_share.rst index a29154cb4..8f22fae50 100644 --- a/source/advanced_features/facebook_login_share.rst +++ b/source/advanced_features/facebook_login_share.rst @@ -20,8 +20,8 @@ Prerequisites Before you begin, ensure you have the following: - - Access to the Facebook Developer Console. - - A Facebook App ID. +- Access to the Facebook Developer Console. +- A Facebook App ID. Integration Steps ----------------- @@ -59,8 +59,10 @@ Creating a Facebook App ID - Go to the App Dashboard. - Click on "Create App" and select the appropriate permissions for your app. - Add Valid OAuth Redirect URIs, including: - - `https://www.talkable.com` - - Your custom domain, if applicable. + + - `https://www.talkable.com` + - Your custom domain, if applicable. + - Save and copy the generated App ID. Error Handling diff --git a/source/advanced_features/file_encryption.rst b/source/advanced_features/file_encryption.rst index 1d47ae910..9a677ddc0 100644 --- a/source/advanced_features/file_encryption.rst +++ b/source/advanced_features/file_encryption.rst @@ -66,7 +66,3 @@ To decrypt a file simply call GPG on it: gpg file_name.asc .. _How To Use GPG to Encrypt and Sign Messages: https://www.digitalocean.com/community/tutorials/how-to-use-gpg-to-encrypt-and-sign-messages#set-up-gpg-keys - -.. container:: hidden - - .. toctree:: diff --git a/source/advanced_features/multi_currency.rst b/source/advanced_features/multi_currency.rst index dc1dfa53b..a2ad2cbf5 100644 --- a/source/advanced_features/multi_currency.rst +++ b/source/advanced_features/multi_currency.rst @@ -67,9 +67,9 @@ with the currency pre-selected: Currency can also be provided directly in any of the following function calls, overriding the `authenticate_customer` data: - - `register_affiliate` - - `register_purchase` - - `register_event` +- `register_affiliate` +- `register_purchase` +- `register_event` For example: @@ -143,7 +143,7 @@ discounts in their familiar currency, enhancing transparency and trust during in For example: -* A fixed discount of **$10 USD** will display as **€9 EUR** if the conversion rate at the time of checkout is 1 USD = 0.9 EUR. + A fixed discount of **$10 USD** will display as **€9 EUR** if the conversion rate at the time of checkout is 1 USD = 0.9 EUR. Shopify performs this conversion dynamically based on the customer's selected currency, simplifying the shopping experience for international buyers. For more details, refer to Shopify's guide on diff --git a/source/advanced_features/passing_custom_data.rst b/source/advanced_features/passing_custom_data.rst index 0f3b5db64..699c3c23b 100644 --- a/source/advanced_features/passing_custom_data.rst +++ b/source/advanced_features/passing_custom_data.rst @@ -83,7 +83,3 @@ Key-Value pairs can be referenced calling the desired data key, such as: Any ``custom_properties`` data passed through is tied to the |advocate|, |friend|, or |loyalty_member|. If Talkable receives a custom property that was previously defined for the user, the property gets overwritten with a new value. - -.. container:: hidden - - .. toctree:: diff --git a/source/advanced_features/personal_coupon_sharing.rst b/source/advanced_features/personal_coupon_sharing.rst index be0c91a09..fdd8c3923 100644 --- a/source/advanced_features/personal_coupon_sharing.rst +++ b/source/advanced_features/personal_coupon_sharing.rst @@ -7,8 +7,8 @@ Advocate Personal Coupon Sharing ================================ .. note:: - This is an experimental feature, please ask your Customer Success Manager - to apply it into your campaigns. + This is an experimental feature, please ask your Customer Success Manager + to apply it into your campaigns. At Talkable Advocates can invite Friends in two ways: @@ -119,14 +119,10 @@ As a result each Advocate may have multiple personal coupons associated with the **Q: What characters are allowed in the personal coupon?** A: Here is a list of validation rules that are defined globally for any coupons: - #. Coupon should be unique on a site level - #. Coupon value cannot be “SAMPLE-COUPON-CODE” (in any case) - #. All coupons are case insensitive, they are always normalized to uppercase and UTF8 encoding - #. Coupon length is between 3 and 255 characters + +#. Coupon should be unique on a site level +#. Coupon value cannot be “SAMPLE-COUPON-CODE” (in any case) +#. All coupons are case insensitive, they are always normalized to uppercase and UTF8 encoding +#. Coupon length is between 3 and 255 characters Any UTF8 characters are allowed (including spaces). - - -.. container:: hidden - - .. toctree:: diff --git a/source/advanced_features/reg_ex.rst b/source/advanced_features/reg_ex.rst index 1e03ae270..5c73de3cb 100644 --- a/source/advanced_features/reg_ex.rst +++ b/source/advanced_features/reg_ex.rst @@ -130,7 +130,3 @@ formats: * `http://site.com/test/products/one` * `http://stage.com/products/two` * `http://test.com/test/products/one/deep?utm=test` - -.. container:: hidden - - .. toctree:: diff --git a/source/advanced_features/rybbon.rst b/source/advanced_features/rybbon.rst index f42109ef3..ed9715fa1 100644 --- a/source/advanced_features/rybbon.rst +++ b/source/advanced_features/rybbon.rst @@ -36,11 +36,11 @@ Example Usage 2. **Custom Reward Amount for Rybbon Campaigns** -Allows setting a custom reward amount for Rybbon campaigns with variable denomination. The minimum amount conforms to specific Rybbon gift card restrictions, and the maximum is 50. + Allows setting a custom reward amount for Rybbon campaigns with variable denomination. The minimum amount conforms to specific Rybbon gift card restrictions, and the maximum is 50. -.. code-block:: liquid + .. code-block:: liquid - {{ "a9a3472f4ea858758e0cd686de8408e2" | rybbon: amount: 13.5 }} + {{ "a9a3472f4ea858758e0cd686de8408e2" | rybbon: amount: 13.5 }} Limitations ----------- diff --git a/source/advanced_features/segments.rst b/source/advanced_features/segments.rst index bf249f1c7..f5dc1857c 100644 --- a/source/advanced_features/segments.rst +++ b/source/advanced_features/segments.rst @@ -102,7 +102,3 @@ In this example, `segment1`, `segment2`, and `segment3` attributes are passed th This approach simplifies custom data handling for customers, allowing for unified data across various methods and optimizing segmentation management without additional calls. -.. container:: hidden - - .. toctree:: - diff --git a/source/advanced_features/shopify_coupons_auto_apply.rst b/source/advanced_features/shopify_coupons_auto_apply.rst index 55c5d065c..10190bc0e 100644 --- a/source/advanced_features/shopify_coupons_auto_apply.rst +++ b/source/advanced_features/shopify_coupons_auto_apply.rst @@ -45,15 +45,11 @@ This method involves including the discount code in the URL. This way, when a cu **Breakdown:** - - `{{ site_setup.url }}/discount/{{ coupon.code }}`: This applies the coupon code to the cart. - - - `?redirect={{ site_setup.url }}`: This redirects the customer back to your store. - - - `&utm_source=talkable&utm_medium={{ sharing_channel }}&utm_content={{ campaign_setup.name | encode_query_argument }}&utm_campaign={{ campaign_setup.id }}`: These are default UTM parameters used for tracking. - - - `&tkbl_cvuuid={{ visitor_uuid }}&talkable_visitor_offer_id={{ friend_offer.id }}`: These parameters are specific to Talkable, to identify customer. - - - `{% if coupon.code %}{% endif %}` - condition to check if we have coupon. + - `{{ site_setup.url }}/discount/{{ coupon.code }}`: This applies the coupon code to the cart. + - `?redirect={{ site_setup.url }}`: This redirects the customer back to your store. + - `&utm_source=talkable&utm_medium={{ sharing_channel }}&utm_content={{ campaign_setup.name | encode_query_argument }}&utm_campaign={{ campaign_setup.id }}`: These are default UTM parameters used for tracking. + - `&tkbl_cvuuid={{ visitor_uuid }}&talkable_visitor_offer_id={{ friend_offer.id }}`: These parameters are specific to Talkable, to identify customer. + - `{% if coupon.code %}{% endif %}` - condition to check if we have coupon. #. **Advocate destination URL:** diff --git a/source/advanced_features/shopify_coupons_auto_sync.rst b/source/advanced_features/shopify_coupons_auto_sync.rst index 961a3727b..b677b1b23 100644 --- a/source/advanced_features/shopify_coupons_auto_sync.rst +++ b/source/advanced_features/shopify_coupons_auto_sync.rst @@ -113,18 +113,13 @@ Shopify Price Rule Changed Email Notification If you modify a Price Rules on Shopify, it could make them incompatible with the coupon lists they are attached to. In order to find out about such changes as early as possible, we have a daily monitoring job that checks that Price Rules have no critical differences from respective coupon lists. Attributes that are checked in this job are the following: - - - `allocation_method` - must always be "across" - - - `usage_limit` - must always be 1 - - - `value` - must correspond to coupon list amount - - - `value_type` - must correspond to coupon list type - - - `ends_at` - must be greater than or equal to coupon list expiration (and absent if coupon list has no expiration) - - - `prerequisite_subtotal_range` - must match coupon list minimum subtotal + +- `allocation_method` - must always be "across" +- `usage_limit` - must always be 1 +- `value` - must correspond to coupon list amount +- `value_type` - must correspond to coupon list type +- `ends_at` - must be greater than or equal to coupon list expiration (and absent if coupon list has no expiration) +- `prerequisite_subtotal_range` - must match coupon list minimum subtotal If any of these attributes differ from what they are expected to be and Talkable cannot fix that by updating a coupon list (see **Coupon list sync**), Talkable sends an email notification. @@ -137,9 +132,8 @@ Talkable tries to keep up with the Price Rules assigned to coupon lists when/if As long as the Price Rule is otherwise valid for a coupon list, we update the coupon list’s: -**expiration date** - only if Price Rule end date is further in the future (or absent) - -**minimum subtotal** +- **expiration date** - only if Price Rule end date is further in the future (or absent) +- **minimum subtotal** .. note:: If there are any other changes in the Price Rule that make it not suitable for a certain coupon list, we won’t sync the coupon list. In this case, a Shopify Price Rule Changed Email Notification will be delivered and action will be required to fix the issue. diff --git a/source/advanced_features/shopify_purchase_syncing.rst b/source/advanced_features/shopify_purchase_syncing.rst index 54c46bf0b..3b8850905 100644 --- a/source/advanced_features/shopify_purchase_syncing.rst +++ b/source/advanced_features/shopify_purchase_syncing.rst @@ -63,10 +63,9 @@ In this setup Purchase Syncing is just ensuring that attributes passed with Java and notifies Talkable Integrations team in case it is not. Here is detailed explanation of this logic: + +- Purchase Syncing tries to find Purchase in Talkable by Order Number (Shopify Purchase ID). +- If there is no such Purchase, the one will be registered with attributes described in `Shopify Webhook payload and Talkable Purchase attributes mapping` +- If such Purchase exists, Purchase Syncing compares **Email** and **Subtotal** with Shopify Webhook payload. - - Purchase Syncing tries to find Purchase in Talkable by Order Number (Shopify Purchase ID). - - - If there is no such Purchase, the one will be registered with attributes described in `Shopify Webhook payload and Talkable Purchase attributes mapping` - - - If such Purchase exists, Purchase Syncing compares **Email** and **Subtotal** with Shopify Webhook payload. - In case these attributes differ, Talkable Integrations team will is notified. Otherwise, nothing happens and the existing Purchase data is kept unmodified. +In case these attributes differ, Talkable Integrations team will is notified. Otherwise, nothing happens and the existing Purchase data is kept unmodified. diff --git a/source/advanced_features/single_sign_on.rst b/source/advanced_features/single_sign_on.rst index 1d70168e8..0922ce48c 100644 --- a/source/advanced_features/single_sign_on.rst +++ b/source/advanced_features/single_sign_on.rst @@ -60,16 +60,17 @@ If automatic configuration is not supported by your IdP, then try manual configu Manual Configuration -------------------- -Uncheck the box for “Automatically Configure from Metadata”. +1. Uncheck the box for “Automatically Configure from Metadata”. -Fill in the following fields: +2. Fill in the following fields: - * IdP Issuer (Entity ID) - * IdP SSO Target URL - * X.509 Certificate OR Certificate Fingerprint - (Talkable will automatically generate the fingerprint if the full X.509 certificate is provided) + * IdP Issuer (Entity ID) + * IdP SSO Target URL + * X.509 Certificate OR Certificate Fingerprint + |br| + (Talkable will automatically generate the fingerprint if the full X.509 certificate is provided) -Save the settings. +3. Save the settings. Testing Single Sign-On ---------------------- @@ -93,6 +94,3 @@ Once you've configured SSO, you can test it as followed: .. image:: /_static/img/advanced_features/sso_sp_initiated_url.png -.. container:: hidden - - .. toctree:: diff --git a/source/advanced_features/subscribing_to_events.rst b/source/advanced_features/subscribing_to_events.rst index 5bba0a677..4c73c374c 100644 --- a/source/advanced_features/subscribing_to_events.rst +++ b/source/advanced_features/subscribing_to_events.rst @@ -32,8 +32,8 @@ Knowing the container `name` attribute of the iframe is `talkable-offer-iframe` Notice two arguments passed in the callback: - 1. `data` object — the data passed by the iframe upon firing the event - 2. `iframe` object — iframe’s `HTML DOM reference`_ +- `data` object — the data passed by the iframe upon firing the event +- `iframe` object — iframe’s `HTML DOM reference`_ .. _HTML DOM reference: https://www.w3schools.com/jsref/dom_obj_frame.asp @@ -42,16 +42,13 @@ Iframe Events List Talkable campaigns are equipped with the following set of events: - 1. `offer_loaded` — Talkable iframe DOM ready event which is in fact the very first event that you can use to determine if the iframe is loaded. - 2. `responsive_iframe_height` — fires every time iframe size gets changed. You can use it to detect changes in iframe size. - You can read more :ref:`here `. Previously named as ``curebit_offer_iframe_broadcast``. - 3. `offer_close` — fires when the close button is clicked. You can use this event to determine when user closes Talkable campaign, it then disappears from the screen. - 4. `offer_triggered` — Talkable Trigger Widget iframe fires this event when user clicks on it. You can use this event to detect when the main offer iframe is about to show up. - 5. `coupon_issued` — fires upon issuing coupon code as a reward for sharing. You can use it to determine when the user shares and receives their reward. `data.channel` tells which sharing channel was used and `data.coupon_code` stores the coupon code value. - 6. `share_succeeded` — fires each time |advocate| shares. `data.channel` tells which sharing channel was used for the share. - 7. `email_gating_passed` — fires when |friend| passes email gating on :ref:`Friend Claim Page `. - 8. `email_gating_failed` — fires when |friend| fails to pass email gating on :ref:`Friend Claim Page `. - -.. container:: hidden - - .. toctree:: +1. `offer_loaded` — Talkable iframe DOM ready event which is in fact the very first event that you can use to determine if the iframe is loaded. +2. `responsive_iframe_height` — fires every time iframe size gets changed. You can use it to detect changes in iframe size. + |br| + You can read more :ref:`here `. Previously named as ``curebit_offer_iframe_broadcast``. +3. `offer_close` — fires when the close button is clicked. You can use this event to determine when user closes Talkable campaign, it then disappears from the screen. +4. `offer_triggered` — Talkable Trigger Widget iframe fires this event when user clicks on it. You can use this event to detect when the main offer iframe is about to show up. +5. `coupon_issued` — fires upon issuing coupon code as a reward for sharing. You can use it to determine when the user shares and receives their reward. `data.channel` tells which sharing channel was used and `data.coupon_code` stores the coupon code value. +6. `share_succeeded` — fires each time |advocate| shares. `data.channel` tells which sharing channel was used for the share. +7. `email_gating_passed` — fires when |friend| passes email gating on :ref:`Friend Claim Page `. +8. `email_gating_failed` — fires when |friend| fails to pass email gating on :ref:`Friend Claim Page `. diff --git a/source/advanced_features/tremendous.rst b/source/advanced_features/tremendous.rst index aab3dcfc1..a3e794831 100644 --- a/source/advanced_features/tremendous.rst +++ b/source/advanced_features/tremendous.rst @@ -11,29 +11,30 @@ Reward advocates with gift cards from various retailers provided by Tremendous. Tremendous integration consists of several parts: - 1. A campaign in Tremendous with the selected rewards for customers. +1. A campaign in Tremendous with the selected rewards for customers. - 3. A "Tremendous" application installed from Talkable App Store. This application is responsible - for storing API tokens, enabling Talkable to request gift cards from Tremendous and insert the generated - claim links in the referral campaign theme. +3. A "Tremendous" application installed from Talkable App Store. This application is responsible + for storing API tokens, enabling Talkable to request gift cards from Tremendous and insert the generated + claim links in the referral campaign theme. - 2. A referral campaign in Talkable having the following attributes: +2. A referral campaign in Talkable having the following attributes: - - An Advocate Referral Incentive with "Tremendous" reward type + - An Advocate Referral Incentive with "Tremendous" reward type - .. image:: /_static/img/advanced_features/tremendous_incentive.png - :width: 400 - :alt: Creating a Tremendous Advocate Referral incentive + .. image:: /_static/img/advanced_features/tremendous_incentive.png + :width: 400 + :alt: Creating a Tremendous Advocate Referral incentive - - A :ref:`"tremendous" Liquid filter` used in Reward Paid Email Page. - The filter generates a claim link within the specified Tremendous campaign. + - A :ref:`"tremendous" Liquid filter` used in Reward Paid Email Page. + + The filter generates a claim link within the specified Tremendous campaign. - .. code-block:: html + .. code-block:: html - - - {{ cta_text }} - + + + {{ cta_text }} + **Contact us** diff --git a/source/advanced_features/url_parameters.rst b/source/advanced_features/url_parameters.rst index bda339fa0..9cfadfa2d 100644 --- a/source/advanced_features/url_parameters.rst +++ b/source/advanced_features/url_parameters.rst @@ -28,7 +28,3 @@ integration. .. note:: Don’t forget to escape URL parameters with URI parameter encoder. - -.. container:: hidden - - .. toctree:: diff --git a/source/advanced_features/utm_tags.rst b/source/advanced_features/utm_tags.rst index 78c008c5f..2834f8c92 100644 --- a/source/advanced_features/utm_tags.rst +++ b/source/advanced_features/utm_tags.rst @@ -12,18 +12,15 @@ channels. By correctly implementing UTM tags, marketers can gain valuable insigh the effectiveness of their campaigns and optimize their strategies accordingly. Components of UTM Tags: - - Source (utm_source): Identifies the specific source of the traffic, such as a search engine or newsletter. - - Medium (utm_medium): Specifies the marketing medium, such as email, social, or CPC (Cost Per Click). - - Campaign (utm_campaign): Specifies the name of the marketing campaign. - - Term (utm_term): Used for paid search keywords. - - Content (utm_content): Used to differentiate similar content, such as different versions of an ad. + +- Source (utm_source): Identifies the specific source of the traffic, such as a search engine or newsletter. +- Medium (utm_medium): Specifies the marketing medium, such as email, social, or CPC (Cost Per Click). +- Campaign (utm_campaign): Specifies the name of the marketing campaign. +- Term (utm_term): Used for paid search keywords. +- Content (utm_content): Used to differentiate similar content, such as different versions of an ad. Example of usage: .. code-block:: text https://example1.com/friends?refer=friends&utm_source=example_source&utm_medium=example_medium - -.. container:: hidden - - .. toctree:: diff --git a/source/advanced_features/white_labeling.rst b/source/advanced_features/white_labeling.rst index 7e639f28c..3ba9cb71b 100644 --- a/source/advanced_features/white_labeling.rst +++ b/source/advanced_features/white_labeling.rst @@ -45,7 +45,7 @@ Custom Email and Web domains can be configured in **Site Settings** → **Custom Click "Check DNS status" on Talkable custom domain settings to see the updated status of your domain (it could take up to 24 hours for the records to propagate). -.. image:: /_static/img/advanced_features/custom_domain_missing_records.png + .. image:: /_static/img/advanced_features/custom_domain_missing_records.png .. _delegated-vs-self-managed: diff --git a/source/android_sdk.rst b/source/android_sdk.rst index 018dba3af..ed93203c7 100644 --- a/source/android_sdk.rst +++ b/source/android_sdk.rst @@ -21,14 +21,31 @@ can use the following Talkable capabilities: - Track sales via the App and reward Advocate if a sale was driven through someone’s claim link -Contents: - -.. toctree:: - - android_sdk/getting_started - android_sdk/integration - android_sdk/advanced - android_sdk/api - android_sdk/custom_deep_linking - android_sdk/testing - android_sdk/upgrade +.. raw:: html + +

Contents:

+ +.. grid:: 1 2 2 2 + + .. grid-item:: + + .. toctree:: + :maxdepth: 2 + + android_sdk/getting_started + android_sdk/integration + android_sdk/advanced + + .. grid-item:: + + .. toctree:: + :maxdepth: 2 + + android_sdk/api + android_sdk/custom_deep_linking + android_sdk/testing + + .. toctree:: + :maxdepth: 1 + + android_sdk/upgrade \ No newline at end of file diff --git a/source/android_sdk/advanced.rst b/source/android_sdk/advanced.rst index a7f61f3b9..7f0edf0a1 100644 --- a/source/android_sdk/advanced.rst +++ b/source/android_sdk/advanced.rst @@ -16,13 +16,10 @@ and ``error.getMessage()`` respectively. Here is a list of possible error codes from ``TalkableOfferLoadException`` with descriptions: - ``NETWORK_ERROR``: General network error - - ``API_ERROR``: Talkable API unavailable - - ``REQUEST_ERROR``: Bad request - - ``CAMPAIGN_ERROR``: Campaign not found +- ``NETWORK_ERROR``: General network error +- ``API_ERROR``: Talkable API unavailable +- ``REQUEST_ERROR``: Bad request +- ``CAMPAIGN_ERROR``: Campaign not found Using multiple site slugs ------------------------- @@ -192,7 +189,3 @@ your Android application. .. _`handle configuration changes`: https://developer.android.com/guide/topics/resources/runtime-changes.html .. _`Fragment`: https://developer.android.com/guide/fragments .. _`Fragment Transactions`: https://developer.android.com/guide/fragments/transactions - -.. container:: hidden - - .. toctree:: diff --git a/source/android_sdk/api.rst b/source/android_sdk/api.rst index 039e5d2ef..c5d3cd9f3 100644 --- a/source/android_sdk/api.rst +++ b/source/android_sdk/api.rst @@ -13,7 +13,7 @@ Create visitor It’s the simplest method. You don’t need anything to create `Visitor`. But you can do anything you need with just create one. - .. code-block:: java +.. code-block:: java import com.talkable.sdk.TalkableApi; @@ -39,10 +39,12 @@ You need to build `Origin` to create. There are three subclasses of this class. Hierarchy ......... - * `Origin` (Abstract) - * `AffiliateMember` - * `Event` - * `Purchase` +* `Origin` (Abstract) + + * `AffiliateMember` + * `Event` + + * `Purchase` Building Origin ............... @@ -218,19 +220,15 @@ Use the ``createSocialShare`` method to track a social share. .. code-block:: java - SharingChannel channel = SharingChannel.FACEBOOK; // required - SocialOfferShare share = new SocialOfferShare(offer, channel); - TalkableApi.createSocialShare(share, new Callback2() { - @Override - public void onSuccess(SocialOfferShare createdShare, Reward reward) { - // Process success - } - @Override - public void onError(ApiError e) { - // Process error - } - }); - -.. container:: hidden - - .. toctree:: + SharingChannel channel = SharingChannel.FACEBOOK; // required + SocialOfferShare share = new SocialOfferShare(offer, channel); + TalkableApi.createSocialShare(share, new Callback2() { + @Override + public void onSuccess(SocialOfferShare createdShare, Reward reward) { + // Process success + } + @Override + public void onError(ApiError e) { + // Process error + } + }); diff --git a/source/android_sdk/getting_started.rst b/source/android_sdk/getting_started.rst index 0a44dce7b..94d6f12c8 100644 --- a/source/android_sdk/getting_started.rst +++ b/source/android_sdk/getting_started.rst @@ -113,7 +113,7 @@ Installation Here is an example of ``AndroidManifest.xml`` file (with ``"demo-site"`` site ID) you should setup after steps above: - .. code-block:: xml +.. code-block:: xml