There are currently 3 sources of documentation for Bitxor. Feel free to jump to the one you are interested in.
Technical documentation
Content
This is the main technical reference for Bitxor. 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 Bitxor 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:
After that you can trigger a build by running from the repository’s root:
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.
Note
On Windows you have a handy make-win.bat that does the same thing but takes care of some Windows shenanigans like incorrect console output and filesystem monitoring.
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.
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 Bitxor community, even committing the updated texts and submitting pull requests.
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.
Working documentation
This is meant as a scratch pad for collaborative editing, or as a means of storage for documents that change too often or are too big or numerous to be in the Handbook.
Examples are:
Documents being worked on (they are live, or waiting approval to go into the Handbook)
Meeting minutes (there are too many of them)
Test results (they change continuously)
To keep this area organized all documents should be tagged. Please add this line at the bottom of your document:
###### tags: `tag1` `tag2`
Use any tag you want, but please look at the other documents and try to be consistent.
Caution
If you don’t use a tag your document will appear in the Untagged section and you will be severely reprimanded.
Last updated by Administrator
on 2022‑09‑27.
