Iroha reStructuredTest documentation

The purpose of this documentation is to convey design and architecture aspects of Iroha ledger in a structured approach, as well as operational side: how-tos, guides, and examples. Docs are accessible via ReadTheDocs website, and can be generated to a lot of formats, available in Sphinx. In order to contribute, one should be familiar with reStructuredTest syntax, and follow principles described in this file.

Principles

• modify only the contents of image_assets and source folders
• do make permissions in case of any change inside source/permissions folder
• if new section/file is added — it should be placed in the list of contents
• if any new principle is added — it should be discussed in GitHub issues first, as an improvement proposal
• reference images or assets using GitHub download link or an external service, since our localized docs can't use relative path to image assets or other resources

Setup

Generally, the docs are available via ReadTheDocs website. Although, to check the result locally, you can build them manually, by following this routine:

Prerequisites

• Python 2.7 or Python 3.3+, and pip installed
• Installed sphinx
• Run pip install -r requirements.txt in docs/source

Build steps

1. cd docs/source
2. make permissions
3. make html

After that, the documentation is generated in html format in _build folder. You can check another formats on Sphinx website or just by typing make. In order to get familiar with the syntax of theme used in the project please go to their demo website

How to generate a version of docs for the target language

In essence, the flow of docs generation is described on the following page of Sphinx documentation. Shortly saying, there should be following steps performed:

1. pip install sphinx-intl
2. For each correction of an original english source test, gettext command should be invoked as here: make gettext
3. Update/create locale for docs invoking the sphinx-intl binary: sphinx-intl update -p _build/gettext -l de -l ja, which creates Japanese and German locale files.
4. Target project is generated by this command make -e SPHINXOPTS="-D language='de'" html (for German)

Got troubles with binary of sphinx-intl on Mac? Check if you have added it into PATH, usually it should be as following: $PATH:$HOME/Library/Python/2.7/bin.