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
.