Table of Contents
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):
./scripts/build_doc.sh
This will spawn Jekyll in preview mode and serve the documentation at 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. 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:
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:
---
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:
$ ./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. 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. Some of the CSS and Javascript parts that are required are available here.