Link Search Menu Expand Document
Sonos API

Development of unofficial Sonos Documentation

A lot of the files you see in this repository are generated with a custom build generator. This page describes how everything works together.

Live preview on local machine

We created a docker-compose.yml file so you can really easy see the resulting webpage on your local machine. Go to the docs folder and start the docker container that will compile the document source to a webpage on every save.

cd ./docs

# Run container (in foreground, will stop with CTRL+C)
docker-compose up docs

Once you have this running it will show some output about installing some ruby packages (inside the container, no worries). And then show the following message, this means the page is now available at http://localhost:4000:

docs_1  | Configuration file: /srv/jekyll/_config.yml
docs_1  |             Source: /srv/jekyll
docs_1  |        Destination: /srv/jekyll/_site
docs_1  |  Incremental build: enabled
docs_1  |       Generating...
docs_1  |       Remote Theme: Using theme svrooij/just-the-docs
docs_1  |        Jekyll Feed: Generating feed for posts
docs_1  |    GitHub Metadata: No GitHub API authentication could be found. Some fields may be missing or have incorrect data.
docs_1  |                     done in 4.873 seconds.
docs_1  |                     Auto-regeneration may not work on some Windows versions.
docs_1  |                     Please see: https://github.com/Microsoft/BashOnWindows/issues/216
docs_1  |                     If it does not work, please upgrade Bash on Windows or run Jekyll with --no-watch.
docs_1  |  Auto-regeneration: enabled for '/srv/jekyll'
docs_1  | LiveReload address: http://0.0.0.0:35729
docs_1  |     Server address: http://0.0.0.0:4000//
docs_1  |   Server running... press ctrl-c to stop.
docs_1  |         LiveReload: Browser connected

documentation.json

The documentation.json file is where we could use some help. You don’t need to know programming to describe all the actions sonos has.

This file is used as one of the inputs for the generator. It allows us to set a nice description for each service and action. It also offers a way to describe each input/output parameter.

For example this part is the source for the documentation you see on this page.

Custom generator

We build a custom generator to do several things.

Discover services from Sonos speaker

You can use the generator to generate device discovery files. For each model we generated a discovery json, as available on main page. We generate this file by parsing the device discovery document available at http://{sonos_ip}:1400/xml/device_description.xml. Not every model has the same services, but it seems that if a service is available it’s the same as all other models that have that service.

(Re)generate discovery files:

# Fork the repository
# Clone to local folder
# Go to folder
cd /generator/sonos-docs
# Install required packages
npm install
# on Windows
.\bin\run services {sonos-ip}
# on Unix/Mac
./bin/run services {sonos-ip}

Please help us out occasionally by running this command on your own Sonos speaker and send us the resulting file. This way we can keep the discovery files up to date. This command will automatically update the discovery files in the data folder. These files are used as an input for the generator. Having up to date discovery files will help us to keep the documentation up to date. All personal identifiable information is removed from the discovery files.

Combine discovery files and documentation

If you changed the documentation.json file or if you added/updated discovery files, you need to combine the two into one file, the .cache/combined.json file.

This file is the result of the the manual documentation and the device discovery files. This file is almost 8000 lines of json at the moment, which is why it is ignored in git. Being able to inspect this json file should really help in debugging the generator.

You can generate this file by running the following command:

# Fork the repository
# Clone to local folder
# Go to folder
cd /generator/sonos-docs
# Install required packages
npm install
# on windows short for .\\bin\\run combine --docsFile=../../docs/documentation.json --folder=data
npm run intermediate-win
# on Unix/mac short for ./bin/run combine --docsFile=../../docs/documentation.json --folder=data
npm run intermediate

# or with npx from the root directory
npx @svrooij/sonos-docs combine --docsFile=./docs/documentation.json --folder=./generator/sonos-docs/data --out=./generator/sonos-docs/.cache/combined.json

Regenerate documentation

Once you generated the combined.json file, you can use the generator to (re)generate the service documentation. This step is mandatory if you changed either the documentation.json or if you added/updated one of the discovery files.

The resulting files, are not to be changed manually, since changes will get lost upon the next generation.

Template Resulting file(s)
services-index.hbs docs/services/index.md
service.hbs docs/services/*.md

Regenerate documentation:

# Fork, clone, go to '/generator/sonos-docs' and run npm install
# generate combined.json, see above

# Regenerate documentation
# on windows, short for .\\bin\\run generate docs ../../docs
npm run docs-win
# on unix/mac, short for ./bin/run generate docs ../../docs
npm run docs

# or with npx (from root folder)
npx @svrooij/sonos-docs generate docs ./docs -i ./generator/sonos-docs/.cache/combined.json

Use generator for other library

The generator uses Handlebars templates. A template is actually a folder with at least a template.json file and one or more template files.

The template.json file gives some basic information about the template, the author of that template and which files to use.

  1. File usage index, will use the data from intermediate.json as input to produce one file.
  2. File usage service, will use the data from each service to produce one file per service, be sure to use {snService} or {service} in the outputFile.

Be sure to check out the docs template to get started. Or the ts template, which is used to generate Sonos typescript.

# Fork, clone, go to '/generator/sonos-docs' and run npm install
# generate combined.json, see above

# generate library
# [template-folder] can either be a folder relative to the current location, a full path to a template folder or the name of the folder inside the generator folder.
# [root-output-folder] in what folder (relative or full path) should the resulting files be placed. 
# on windows
.\bin\run generate [template-folder] [root-output-folder]
# on unix/mac
./bin/run generate [template-folder] [root-output-folder]

# or with npx
npx @svrooij/sonos-docs generate [template-folder] [root-output-folder] -i ./generator/sonos-docs/.cache/combined.json