bofhcoin / exonum-doc

Exonum documentation

Exonum Documentation

This is the documentation repo for the Exonum platform. It contains source files used to build the documentation displayed on the Exonum website.

The Exonum documentation is written in Markdown, and uses mkdocs to generate HTML from sources. You can read about Markdown here or other places.

Contributing

In order to contribute, fork this repository, make some changes, and then submit them as a pull request. Simple! Note that the repository uses master / develop branching to allow for continuous deployment on the exonum.com website.

Notice that the repository uses a set of linters to check possible problems with the contributed documents:

• markdownlint is used to lint Markdown files. Please see the rules list to fix possible problems with this linter
• html5validator is used for checking problems with the generated HTML pages
• linkchecker is used to find missing links
• cspell is used for spellchecking

You can set up these tools locally (see the install step in the Travis config for more details) and run them using the ./misc/lint.sh script with md, html, links, cspell, or all arguments.

Page Meta

During the build process, mkdocs gathers meta information for each page, which is then used to provide page summary on social media, for search engines, etc. The main meta information of interest is the page description. By default, it is equal to the first paragraph of the page. You can override this default by providing an explicit description on the very top of the page with a front matter formatting:

---
description: 1-3 sentence description of the page
---
# Page Title

Page contents...

Similarly, you can redefine the displayed page title by providing a title property in the front matter. The site-wide “Exonum Documentation” suffix will be added automatically.

Note. Although it looks like YAML front matter in Jekyll and some other static site generators, mkdocs actually uses a simpler parser for the front matter. Be advised for possible discrepancies.

Build Instructions

It is a good idea to preview your changes locally before sending a pull request.

Installation

First, you need to install Python and python-pip. Then, install the mkdocs theme together with its dependencies:

pip install -r requirements.txt

You may use requirements.lock instead of requirements.txt in order to get repeatable builds.

To install linters, use

pip install -r dev-requirements.txt

markdownlint and cspell need to be installed separately. Both these tools utilize Npm package manager, so you can install them using

npm install

(you will need Node 8+ installed).

Viewing Documents Locally

In order to run a local web server serving docs, use:

mkdocs serve

The web server will be available on 127.0.0.1:8000.

To generate HTML files from the Markdown source files, use:

mkdocs build

The generated pages will be available in the site/ directory.

License

Copyright 2018, Exonum Team

The Exonum documentation is licensed under the Creative Commons Non-Commercial Share-Alike International License (version 4.0). Code samples are licensed under the Apache License (version 2.0). See LICENSE and LICENSE-CODE for details.