Repository structure

Content

This is the main technical reference for Symbol. 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 docs-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 locally

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. Basically, you need to:

• Install Python 3.7

• Run pip install -r requirements.txt

After that you can trigger a build by running from the repository's root:

make livehtml

This generates all HTML files in the build/html folder, including all assets like images, javascript, CSS, code snippets, etc. This also monitors your source folder and regenerates the output when changes are detected. It also instantiates a web server on localhost:8000 for your convenience.

Deployment

The GitHub repository is linked to Jenkins, so on every push to the main branch a full build is triggered (See Jenkinsfile). 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.

  If you are sure a link is correct but linkcheck on Travis keeps failing, you can add this particular link to the linkcheck_ignore list in conf.py to skip checking it. Please add a comment explaining the reason.

• Localization: Text strings are extracted from every page using make gettext and uploaded to Transifex (see next section).

• Publishing: The built HTML pages are moved to the docs folder in the gh-pages branch and pushed. GitHub pages is configured to serve them from there.

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 Travis extracts and sends all strings (.pot files) to Transifex, which detects any new or updated text and notifies the translators.

Translators can log in to Transifex and provide the translations there. Developers can then download the updated text (.po files) and commit them to the source repository.

So far this process has been entirely done by the Symbol community, even committing the updated texts and submitting pull requests.

Content

These are the old NEM NIS1 docs, which were spread over several repos, blogs and forum posts, ported over a to single repository. This documentation is rather old and parts of it are still being figured out.

The old docs were mainly hosted at docs.nem.io from the github.com/saulgray/nemioDev repository using the Grav Engine.

A much simpler GitHub page is setup now, using the Jekyll Engine provided by GitHub, using plain Markdown. All content is in the gh-pages branch.

Editing

This repository follows the docs-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 locally

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.

Follow GitHub's instructions to install a local Jekyll instance and run it.

Deployment

Deployment is straightforward since a standard GitHub pages setup is used (GitHub repo + Jekyll site + GitHub pages). Just push to the gh-pages branch and it will be published in seconds.