Table of Contents
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):
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.
_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.
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.
At the top of the site there are a few buttons, e.g.
Support. These buttons are generated by
_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
support in this case (due to link being
When creating the actual page, you need to make sure that
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 ...
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.
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
_config.yml and then create a new file for it under
docs/development. You can look at for instance
device_info.md for inspiration.
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
verify instead will check if it is already up-to-date. This check is done by
tox 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