Sphinx Documentations

This section will guide you through the setup of a sphinx project using the Riptide repository.

Sphinx is a documentation generation tool. This documentation uses Sphinx, so we will use this documentation as an example.

The project we set up uses sphinx-autobuild as a file-watcher and HTTP server for the documentation.

This guide assumes you have Riptide fully set up, with shell integration enabled and a running proxy server (for this guide we assume https://riptide.local as base URL of your proxy server). It also assumes you have the repos part of the configuration set to only the Riptide Community Repository (the default).

Sphinx and Python do NOT need to be installed for this guide.

Preparing the project

For this guide we will use this documentation as an example.

Clone https://github.com/Parakoopa/riptide-docs.git somewhere via Git, or download the repository via Github.

Delete the riptide.yml file (we don’t want Spoilers :) ).

Creating a basic riptide.yml

Create a riptide.yml with the following contents:

project:
  name: riptidedocs
  src: .
  app:
    $ref: /app/sphinx/latest
    services:
      sphinx:
        environment:
          REQUIREMENTS_FILE: "requirements_docs.txt"
          SPHINX_SOURCE: source
          SPHINX_BUILD: build

This file contains one project named riptidedocs. We specify with src that the source code for this project is in the same directory that the riptide.yml is in.

This project contains an app. We load this app from the repository (/app/sphinx/latest, Github <https://github.com/Parakoopa/riptide-repo/tree/master/app/sphinx>) This app has one service called sphinx. This service is the container specification for our Hello World app.

The service sphinx is already specified in the app we loaded from the repository.

However we need to set some important environment variables. SPHINX_SOURCE and SPHINX_BUILD contain the paths to the source and build directories. With REQUIREMENTS_FILE an additional file can be specified that contains requirements that will be installed on start. In our case, Riptide is installed before the documentation server starts.

Running the project setup

Run riptide setup --skip to initiate the project. Since we have not added any setup instructions or files to import (and /app/sphinx/latest also doesn’t define any), we just skip the setup with the --skip flag.

Starting the project

Since the project’s dependencies (express) are now installed, you can open the front page of the Proxy server (https://riptide.local). You will find a new project called riptidedocs.

Click on the link and the project will start. After the start you may get a Gateway Timeout. Wait a while and refresh and you should see this documentation.

Commands

/app/sphinx/latest also defines commands. You can list them with riptide cmd.