---
layout: template
title: Documentation
permalink: /internals/documentation
link_group: internals
---
# :books: Table of Contents
{:.no_toc}
* TOC
{:toc}

# Documentation

This section describes how to work with the pyatv documentation, i.e. the site you are currently
reading.

# Building the Documentation

To preview changes you make before pushing them to GitHub, run this script (only tested on Linux):

```shell
./scripts/build_doc.sh
```

This will spawn Jekyll in preview mode and serve the documentation at [http://localhost:4000](http://localhost:4000). Changes are picked up and re-generated automatically. Note that Docker is required to run this script.

If you make changes to `_config.yml`, you need to restart the script for them to take effect. If you make changes to indirect dependencies, e.g. `page_links:` in `_config.yml`, it will not be enough to restart the script. You will either have to make a dummy modification to your file (for instance use the `touch <file>` command) or remove `_site` prior to starting the script. This is because the information under `page_links:` might be used by your page but Jekyll doesn't know that, so it won't re-generate that page and serve the cached version instead.

# Updating Documentation

All documentation is written in markdown. One resource is [this one](https://guides.github.com/features/mastering-markdown/). The index page is `docs/index.md` and other pages are located in sub-directories, e.g. `docs/development`. You can just go ahead and make simple changes like spelling errors and clarifications directly and push a PR. If you want to add new pages, continue reading.

## Navigation

At the top of the site there are a few buttons, e.g. `Development` and `Support`. These buttons are generated by `top_pages:` in `_config.yml`. To add a new button, just extend this list. There are already too many buttons, so please try placing your changes on a new subpage instead.

Subpage navigation links are shown below the buttons but above the actual content. Each section, e.g. `Development` can have its own subpages and are defined under `page_links:`. A basic example:

```yml
top_pages:
  - link: /support/
    title: Support

page_links:
  support:
    - link: /support/
      title: Start
    - link: /support/migration/
      title: Migration
```

The key used under `top_pages:` should be the same key that is used under `page_links:`, i.e. `support` in this case (due to link being `/support/`).

When creating the actual page, you need to make sure that `permalink` and `link_group` is correctly set, otherwise the navigation won't work. Here is an example based on the configuration above:

```markdown
---
layout: template
title: Migration
permalink: /support/migration/
link_group: support
---
# Migration

...
```

Since `permalink` is used to say how the page is accessed, location of the source file doesn't really matter. But try to keep the structure that is already in place as it makes it easier to find pages.

## Interfaces

In general each interface should have its own page under `Development`. So when adding a new interface (or extending an existing one), make sure you add a new subpage for that interface. Start by adding it to `page_links:` in `_config.yml` and then create a new file for it under `docs/development`. You can look at for instance `device_info.md` for inspiration.

## API Reference

Unfortunately there are no API reference libraries for Jekyll (at least not that works with GitHub Pages). So it cannot be automatically generated by jekyll. As a workaround, the API reference is manually updated and checked into the repository. The API reference is located under `docs/api` and can be updated by calling:

```shell
$ ./scripts/api.py generate
```

Calling with `verify` instead will check if it is already up-to-date. This check is done by `chickn` and it will fail the build in case something has changed. So if you forget to update the API, you will be notified of this (your PR will not be possible to merge).

The API reference is generated using [pdoc3](https://pdoc3.github.io/pdoc/). To make it work with the rest of the site, the default HTML template has been modified to add some frontmatter (for `permalinks` and those parts) as well as not adding default HTML tags, like `<html>`. The pdoc specific parts can be found [here](https://github.com/postlund/pyatv/tree/master/docs/pdoc_templates). Some of the CSS and Javascript parts that are required are available [here](https://github.com/postlund/pyatv/tree/master/docs/assets).
