Audience: Anyone who would like to contribute to the Fabric documentation.
This short guide describes how the Fabric documentation is structured, built and published, as well as a few conventions that help writers make changes to the Fabric documentation.
In this topic, we’re going to cover:
- An introduction to the documentation
- Repository folder structure
- International language folder structure
- Making documentation changes
- Building the documentation on your local machine
- Building the documentation on GitHub with ReadTheDocs
- Getting your change approved
- Making a change to Commands Reference
- Adding a new CLI command
The Fabric documentation is written in a combination of Markdown and reStructuredText source files. As a new author you can use either format. We recommend that you use Markdown as an easy and powerful way to get started. If you have a background in Python, you may prefer to use rST.
During the documentation build process, the documentation source files are converted to HTML using Sphinx. The generated HTML files are subsequently published on the public documentation website. Users can select both different languages and different versions of the Fabric documentation.
- Latest version of US English
- Latest version of Chinese
- Version 2.2 of US English
- Version 1.4 of US English
For historical reasons, the US English source files live in the main Fabric repository, whereas all international language source files live in a single Fabric i18n repository. Different versions of the documentation are held within the appropriate GitHub release branch.
Both the US English and international language repositories have essentially the same structure, so let’s start by examining the US English source files.
All files relating to documentation reside within the
fabric/docs ├── custom_theme ├── source │ ├── _static │ ├── _templates │ ├── commands │ ├── create_channel │ ├── dev-setup │ ├── developapps │ ├── diagrams │ ... │ ├── orderer │ ├── peers │ ├── policies │ ├── private-data │ ├── smartcontract │ ├── style-guides │ └── tutorial └── wrappers
The most important folders is
source/ because it holds the source language
files. The documentation build process uses the
make command to convert these
source files to HTML, which are stored in the dynamically created
fabric/docs ├── build │ ├── html ├── custom_theme ├── source │ ├── _static │ ├── _templates │ ├── commands │ ├── create_channel │ ├── dev-setup │ ├── developapps │ ├── diagrams ...
Spend a little time navigating the docs folder in the Hyperledger Fabric repository. Click on the following links to see how different source files map to their corresponding published topics.
/docs/source/index.rstmaps to Hyperledger Fabric title page
/docs/source/developapps/developing-applications.rstmaps to Developing applications
/docs/source/peers/peers.mdmaps to Peers
We’ll see how to make changes to these files a little later.
The international language repository,
almost exactly the same structure as the
fabric repository which holds the US
English files. The difference is that each language is located within its own
fabric-docs-i18n/docs └── locale ├── ja_JP ├── ml_IN ├── pt_BR └── zh_CN
Examining any one of these folders shows a familiar structure:
locale/ml_IN ├── custom_theme ├── source │ ├── _static │ ├── _templates │ ├── commands │ ├── dev-setup │ ├── developapps │ ├── diagrams │ ... │ ├── orderer │ ├── peers │ ├── policies │ ├── private-data │ ├── smartcontract │ ├── style-guides │ └── tutorial └── wrappers
As we’ll soon see, the similarity of the international language and US English folder structures means that the same instructions and commands can be used to manage different language translations.
Again, spend some time examining the international language repository.
To update the documentation, you simply change one or more language source files in a local git feature branch, build the changes locally to check they’re OK, and submit a Pull request (PR) to merge your branch with the appropriate Fabric repository branch. Once your PR has been reviewed and approved by the appropriate maintainers for the language, it will be merged into the repository and become part of the published documentation. It really is that easy!
As well as being polite, it’s a really good idea to test any documentation changes before you request to include it in a repository. The following sections show you how to:
- Build and review a documentation change on your own machine.
- Push these changes to your GitHub repository fork where they can populate your personal ReadTheDocs publication website for collaborators to review.
- Submit your documentation PR for inclusion in the
Use these simple steps to build the documentation.
Install the following prerequisites; you may need to adjust depending on your OS:
For US English:
git clone firstname.lastname@example.org:hyperledger/fabric.git cd fabric make docs
For International Languages (Malayalam as an example):
git clone email@example.com:hyperledger/fabric-docs-i18n.git cd fabric-docs-i18n make docs-lang-ml_IN
makecommand generates documentation html files in the
docs/build/html/folder which you can now view locally; simply navigate your browser to the
docs/build/html/index.htmlfile. For International Languages, you need to read
Now make a small change to a file, and rebuild the documentation to verify that your change was as expected. Every time you make a change to the documentation you will of course need to rerun
If you’d like, you may also run a local web server with the following commands (or equivalent depending on your OS):
sudo apt-get install apache2 cd docs/build/html sudo cp -r * /var/www/html/
You can then access the html files at
Building on GitHub¶
It is often helpful to use your fork of the Fabric repository to build the Fabric documentation so that others can review your changes before you submit them for approval. The following instructions show you how to use ReadTheDocs to do this.
- Go to
http://readthedocs.organd sign up for an account. Choose the “sign up with GitHub” option.
- Fork the
- Import a project. Select your fork of the fabric repository. You will need to create a unique name for the project, such as YOUR_USERNAME-fabric.
- Check in the
Integrationssettings to verify you have one
GitHub incoming webhook.
- From your fork, go to
Settingsin the upper right portion of the screen.
- Find your new webhook. It will begin with
- Scroll to the
Which events would you like to trigger this webhook?setting and unselect
fabric-docs-i18n instead of
fabric in the above instructions if you’re
building an international language translation.
Now, anytime you modify or add documentation content to your fork, this URL will automatically get updated with your changes!
Making a PR¶
You can submit your PR for inclusion using the following instructions.
Pay special attention to signing your commit with the
git commit -s -m "My Doc change"
This states that your changes conform to the Developer Certificate of Origin.
Before your PR can be included in the appropriate
repository, it must be approved by an appropriate maintainer. For example, a
Japanese translation must be approved by a Japanese maintainer, and so on. You
can find the maintainers listed in the following
- US English
CODEOWNERSand their maintainer GitHub IDs
- International language
CODEOWNERSand their maintainer GitHub IDs
Both language repositories have a GitHub webhook defined so that, once approved,
your newly merged content in the
docs/ folder will trigger an automatic build
and publication of the updated documentation.
Note: Documentation maintainers are not able to to merge documentation PRs by clicking the
Merge pull request button. Instead, if you are a documentation maintainer and have approved the PR, simply add the label
doc-merge to the PR and a
Mergify bot that runs every minute will merge the PR.
Commands Reference updates¶
Updating content in the Commands Reference topic requires additional steps. Because the information in the Commands Reference topic is generated content, you cannot simply update the associated markdown files.
- Instead you need to update the
src/github.com/hyperledger/fabric/docs/wrappersfor the command.
- To update the command help text, you need to edit the associated
.gofile for the command that is located under
- Then, from the
fabricfolder, you need to run the command
make help-docswhich generates the updated markdown files under
Remember that when you push the changes to GitHub, you need to include the
_.go file that was modified as well as the
generated markdown file.
This process only applies to English language translations. Command Reference translation is currently not possible in international languages.
Adding a new CLI command¶
To add a new CLI command, perform the following steps:
- Create a new folder under
/fabric/internal/peerfor the new command and the associated help text. See
internal/peer/versionfor a simple example to get started.
- Add a section for your CLI command in
- Create two new files under
/src/github.com/hyperledger/fabric/docs/wrapperswith the associated content:
<command>_preamble.md(Command name and syntax)
make help-docsto generate the markdown content and push all of the changed files to GitHub.
This process only applies to English language translations. CLI command translation is currently not possible in international languages.