Docs Menu
Docs Home
/
MongoDB Meta Documentation
/
Practices and Processes

Snooty

On this page

  • Introduction
  • Installation
  • Usage
  • Prepare an Existing Giza Project to Use Snooty
  • Commands
  • Optional Configuration
  • Bugs

Introduction

Snooty logo

Snooty is a next generation documentation build system aiming to provide a fluid and integrated writing experience.

Note

Snooty is currently in an early testing stage. Expect bugs and gaps in functionality.

Some features:

  • Realtime diagnostics.

  • When hovering over a include, literalinclude, or figure directive path, a tooltip will appear showing the path to the requested file, which you may click to open.

    Note that this will NOT currently work for files generated by Giza (e.g. steps and extracts).

Installation

Important

Snooty is currently only officially supported on macOS 10.13 or later and Linux x86-64.

  1. Download and install Visual Studio Code.

  2. Start Visual Studio Code, press Shift-Command(⌘)-P, type Install 'code' command in PATH, and press Enter. This will install a code command into your path which you can use to start Visual Studio Code from the command-line.

    This will only take effect in new terminal sessions.

  3. Select the Extensions pane by pressing Shift-Command(⌘)-X, search for Snooty, and press Install.

    This may take a moment while Snooty downloads and installs its dependencies.

Usage

The Snooty Visual Studio Code extension will only activate when a folder is loaded into Visual Studio Code with a snooty.toml file in the root.

Example

To load the docs-compass repository with Snooty, run the following:

git clone https://github.com/mongodb/docs-compass.git

Then open the docs-compass project either through the Visual Studio Code UI or with the following command:

code docs-compass/

The docs-compass repository contains a snooty.toml file in its root, so VSCode will launch Snooty.

Once Snooty is launched, Snooty will highlight problematic source lines as you type. By default, yellow underlines indicate a warning, and red underlines indicate an error.

Prepare an Existing Giza Project to Use Snooty

To prepare an existing Giza/Sphinx project to use Snooty, create a snooty.toml file in the root (i.e. adjacent to the conf.py file) of the project.

snooty.toml is a TOML file and contains metadata describing the project.

You can use the following example to start your project:

name = "guides"
[constants]
version = 4.0
package-name-org = "mongodb-org"
pgp-version = "4.0"

Once this file is created, run Visual Studio Code and open the in the project directory. If you are using the terminal, the code <path> command will open Visual Studio Code in the given path.

Currently, Snooty accepts the following fields in snooty.toml:

Field
Required
Description

name

Required

An identifier string giving the name of the project. Should be all lowercase with only word characters, dashes, and underscores.

source

Optional

Default: "source/"

A path under which to find all reStructuredText source files.

constants

Optional

A mapping of values to treat as Source Constants.

intersphinx

Optional

A list of intersphinx inventory URLs.

substitutions

Optional

A mapping of reStructuredText substitutions to globally define across this project.

Commands

Commands in Visual Studio Code allow you to quickly instruct Snooty to perform some action. You run commands by pressing Shift-Command(⌘)-P and typing the name of the command.

Snooty offers the following commands:

Name
Description

snooty.restart

Restart Snooty. This is currently necessary if it crashes, or if you change your snooty.toml configuration file. Eventually, this will be automatic.

snooty.preview

Open an editor pane showing a rendered preview of the currently open source file.

Optional Configuration

Preview Mode

Visual Studio Code has a behavior which some users find undesirable: by default after opening a file, it is placed in preview mode until either you change the file or you double-click on the tab header.

When in preview mode, any additional files that you open will be opened in the current tab rather than opening a new tab.

You can disable this behavior with the following steps:

  • Open the command palette (Command-Shift-P),

  • Choose Open User Settings,

  • Search for preview, and

  • Uncheck Workbench > Editor: Enable Preview

Bugs

This is a pre-pre-pre-alpha release of Snooty. The following are known deficiencies:

  • Diagnostics have wildly wrong line numbers in YAML content.

  • The Snooty project is not automatically reloaded after changes to the configuration file.

  • Some valid content may show diagnostics.

  • Steps, Extracts, and Release are the only supported YAML files.

  • Hovering to open Steps, Extracts, and Release files will not work correctly .

  • Only a single Snooty project at a time may be opened. Opening more than one project is currently undefined behavior.

Back

Practices and Processes

Next

Translation