The doc is served on https://sictiam.github.io/psn-doc/
The documentation website is processed by Jekyll and served thanks to Github Pages. Please follow the installation instructions here.
When installing gems, you might prefer to install them locally thanks to:
bundle install --path vendor/bundle
To launch Jekyll and process assets:
bundle exec jekyll serve
As an alternative to installing Jekyll locally, you can also use Docker and Compose. A docker-compose.yml is provided so all you have to do is:
docker-compose up
and Jekyll will run the site and watch for file changes to automatically rebuild it.
Whether you use Ruby Gems or Docker, it's important to stay up-to-date with GitHub's versions of Jekyll and its plugins, so make sure to regularly run:
bundle update github-pages
or, if you opted for Docker:
docker-compose pull
It seems including markdown files from index.html with {% include my-file.md %} just does a raw paste without processing the markdown. That's why we use (see in index.html) this syntax:
{% capture inc0 %}{% include 0-welcome.md %}{% endcapture %}{{ inc0 | markdownify }}
See more about this issue here.
Kramdown is used so that we can add class and id on created DOM elements. For example to generate a <p class="focus">paragraph</p>:
paragraph
{: .focus}
More info here.
The styling and behavior of the documentation is deeply inspired by meteor docs. The CSS relies on normalize and typeplate.
- document refresh tokens (creation and revocation)
Shorts lists items do not end with punctuation marks:
- first item
- second
- and third
Longer ones (those that contains several sentences) do:
- sentence. Another one;
- sentence;
- sentence. Another one.
For the moment the documentation relies on the following choices, that needs to be discussed:
- no description of subscription callback for the moment, since it remains to be implemented
- replaced Kernel by Ozwillo when we're talking about APIs