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.
Code examples are included from source using
mkdocs-codeinclude-plugin to ensure they are
always up-to-date and correct.
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.
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.
It is a good idea to preview your changes locally before sending a pull request.
To build the docs you need installed:
- Python version 3.7+
- python-pip
- Node version 10+ (actually verified on v10.16.0 and v12)
Fetch and initialize the repository:
git clone https://github.com/exonum/exonum-doc
cd exonum-doc
git submodule update --init --recursive
If you build the docs locally it is recommended to use python virtual environment:
python3 -m venv .env
source .env/bin/activate
Then, install the mkdocs theme together with its dependencies:
pip install -r requirements.txt --src 3rd-party
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
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.
To generate versioned HTML files from the Markdown source files, use:
node run versioned
The generated folders will be available in the version/ directory. It will contain folders named with its versions.
Folder of the latest version will be named latest.
Copyright 2020, 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.