Introduction

Welcome to the Scribe documentation!

This document will teach you how to build documents for Leadpages!

Different repos may use different documentation generators like Slate (mainly for describing our APIs), Sphinx and potentially others.

Scribe is responsible for having a script that goes into each of our repos, building the documentation, and storing the HTML here in the ./site/ directory.

Each repo is responsible for having the source for its documentation.

Running Locally

1. Navigate to the lp-docker repo on your machine
2. Run docker compose up -d scribe
3. Go to http://scribe.docker/

Building documentation

The ./scripts/ directory Scribe repo has the build scripts for each repo.

Building everything

Run the ./scripts/build_all.sh script

# BUILD EVERYTHING
./scripts/build_all.sh

Build for a single repo

1. Make a change in your repo
2. Update the documentation in your repo
   • How this is done depends on the repo (check the Documentation Generators section for more info)
3. Run the build script for your repo (e.g. ./scripts/build_analytics.sh)
4. Review the changes by going to your local scribe instance
5. Make a PR with the new changes

# Example: Build analytics docs
./scripts/build_analytics.sh

Documentation Generators

Slate

Github

For our req based repos we built the req_slate library to generate our API documentation.

We use the slatedocs/slate docker image to build our docker images. The account API is a good example.

Example Slate Projects

Account

• Source Docs
• Output
• Build Script

Analytics

• Source Docs
• Output
• Build Script

Sphinx

Github

Some of our libraries use Sphinx.

Example Sphinx Projects

Req

• Source Docs
• Output
• Build Script

Documenting a new Repo

1. Write docs in whatever format (slate, sphinx, plain html) in a given repo.
2. Add a script to ./scripts/ directory named build_<repo_name>.sh. This script needs to:
   • Go into your repo
   • Generate an HTML site from your docs (a directory that has an index.html and a bunch of self-referential links)
   • Copy that HTML into ./sites/<repo_name> into the Scribe repo. (make sure its idempotent by running it a bunch of times in a row)
3. Add the name of your repo to the REPOS array in the ./scripts/build_all.sh script
4. Add a link to your repo in ./sites/index.html
5. Open a PR with your changes!