Content
This is the main technical reference. It contains (or will contain):
User guides for the different tools (Wallet, CLI, Explorer, etc.), intended for non-heavily-technical readers, including screenshots and step-by-step instructions on how to solve common problems.
Developer tutorials with source code examples in different languages, organized by topics. Ranging from Getting Started to in-depth guides on specific topics.
Concept definitions required to understand the Symbol protocol.
Technical reference guides describing every API and REST endpoint.
Due to the complexity of the technical content, the Sphinx engine and reStructuredText is used instead of the simpler MarkDown format. This enables much more flexibility, so we can use multi-language (tabbed) code snippets, Python macros which automatically retrieve content from GitHub or have more formatting options for complex tables, for example.
Editing
This repository follows the doc-as-code approach, meaning that you treat the documentation as if it was source code.
To contribute you need to check out the Git repository, make your changes and submit a Pull Request to GitHub. The repository maintainers will review your contribution, suggest changes if required and eventually merge it.
Testing
Before submitting a pull request it is a good idea to test your changes locally, to ensure that everything shows as expected and nothing breaks.
You first need to Install Sphinx.
After that you can trigger a build by running from the repository’s root:
This will monitor your source folder and regenerate the output when changes are detected. It also instantiates a web server on localhost:8000 for your convenience.
Note
On Windows you have a handy make-win.bat that does the same thing but takes care of some Windows shenanigans.
Deployment
The GitHub repository is linked to Travis, so on every push to the main branch a full build is triggered (See .travis.yml and the travis folder for details). This involves several steps besides the generation of the output documentation:
Source snippets validation: The guides include lots of source code examples which are actually snippets from complete programs. These programs must compile and pass lint checks at all times and Travis makes sure of this. Right now only the TypeScript programs are checked.
Link checking: All pages are examined to find broken links using make linkcheck. Throttling is enabled to avoid pestering servers too much and getting `HTTP 429 Too Many Requests` errors. Still, sometimes your build fails because of this. If you detect such error in the Travis logs just try again.
Localization: Text strings are extracted from every page using make gettext and uploaded to Transifex (see next section).
Publishing: The built HTML pages are pushed to a different git repository (symbol/symbol.github.io) where they are served via GitHub pages.
Due to this process, pushes to main normally take up to 5 minutes to go live.
Localization
Right now almost every page is available in Japanese besides the original English, but the repository is ready to accept more languages.
Transifex is integrated in the deployment process, so after every push to main any changed strings are uploaded to Transifex where translators can provide text in their own language. So far this process has been done by the Symbol community.
When new translations are available the repo maintainer can download them from Transifex as .po files and commit them, or translators can provide the .po files directly via a Pull Request.
Last updated by