Project documentation for avalon, automatically tested and deployed to getavalon.github.io.
If you find anything wrong with this documentation, you are invited to improve upon it and here's how you can do that.
Prerequisites
Making changes or additions to Avalon's documentation can come in 1 of 2 forms.
- Make a change to any page under pages/, and submit a pull-request (PR)
- Edit and preview each change interactively on your local machine, and then submit a pull-request.
Previewing the documenation prior to submitting a PR is preferred, as it would enable you to actually see what you're doing prior to submitting it for review; this works on a Windows, Mac or Linux, with Docker available.
$ git clone https://github.com/getavalon/core avalon-core
$ set AVALON_CORE=%cd%\avalon-core # cmd
$ $env:AVALON_CORE="$(pwd)\avalon-core" # powershell
$ export AVALON_CORE=$(pwd)/avalon-core # bashSet the environment variable using your shell of choice, either cmd, powershell or bash.
Usage
Next we'll build and run the image. This will host the documentation locally, via mkdocs, and monitor changes you make to any markdown page. Once you've run it, you'll notice a new directory having been created called build/. This is what mkdocs sees and previews for you, it is the result of pre-processing (see below for what exactly it is doing and why).
$ git clone https://github.com/getavalon/docs avalon-docs
$ cd avalon-docs
$ .\build_docker
Sending build context to Docker daemon 16.81MB
Step 1/9 : FROM mottosso/maya:2016sp1
2016sp1: Pulling from mottosso/maya
f402e43879a8: Pull complete
d62c664230cf: Downloading [========================> ] 133.3MB/272.4MB
ef05875d9e72: Download complete
95620efb6266: Download complete
459d317a8b3e: Downloading [=========> ] 127.8MB/689.4MB
3eb7d8a11585: Download complete
$ .\serve_docker
_watch.py: Watching /workspace/pages..
INFO - Building documentation...
INFO - Cleaning site directory
[I 190618 16:06:30 server:296] Serving on http://0.0.0.0:8000
[I 190618 16:06:30 handlers:62] Start watching changes
[I 190618 16:06:30 handlers:64] Start detecting changes
[I 190618 16:07:27 handlers:135] Browser Connected: http://localhost:8000/2.0/guides/Now visit http://localhost:8000 to view the resulting documentation. Any changes you make to the pages markdown files are reflected in this location in real-time. For each edit, here's what happens.
- Each markdown page in
pages/is built intobuild/ - Each markdown page in
build/is converted into HTML intosite/ - Any code snippets are executed and their results are included into the built markdown
- Any references, such as to schemas, are read and converted into markdown
The theme is built with mkdocs and based on squidfunk/mkdocs-material, with some changes and additions.
For each version of Avalon, a new series of pages are made such that each version may be documented in full without a newer version overshadowing an older one.
Placeholders are added where live code is injected at build time. This ensures that reference material, such as schemas, is never out of date and tell you when there is anything amiss, such as missing example material.
{{schema:subset-2.0.json}}
Every Python snippet in this documentation is executed during build, including interactively as you edit the documentation on your local machine. The results of the execution is included into the documentation itself.
This ensures that no example code carries any errors and is up to date with the actual code it is referring to. It's also handy to know whether the code you write actually runs!
As Avalon is cross-platform, it's important that each OS-specific snippet of code is compatible with your favorite platform. The documentation includes tabs for such occasions. Additionally, changing one tab automatically changes all other tabs, as it is assumed you are only ever interested in snippets for a single platform at a time. For convenience, the active tab as you read is based on your current OS, such as Windows or Linux.