Contributing documentation¶
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
Introduction¶
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.
For example:
- 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.
Repository folders¶
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/
folder:
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/
becuase 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 build/html/
folder:
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.rst
maps to Hyperledger Fabric title page/docs/source/developapps/developing-applications.rst
maps to Developing applications/docs/source/peers/peers.md
maps to Peers
We”ll see how to make changes to these files a little later.
International folders¶
The international language repository,
fabric-docs-i18n
, follows
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
folder within docs/locale/
:
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.
Making changes¶
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
fabric
orfabric-docs-i18n
repository.
Building locally¶
Use these simple steps to build the documentation.
Create a fork of the appropriate
fabric
orfabric-i18n
repository to your GitHub account.Install the following prerequisites; you may need to adjust depending on your OS:
For US English:
git clone git@github.com:hyperledger/fabric.git cd fabric make docs
For International Languages (Malayalam as an example):
git clone git@github.com:hyperledger/fabric-docs-i18n.git cd fabric make docs-lang-ml_IN
The
make
command generates documentation html files in thebuild/html/
folder which you can now view locally; simply navigate your browser to thebuild/html/index.html
file.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
make docs
.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 build/html sudo cp -r * /var/www/html/
You can then access the html files at
http://localhost/index.html
.You can learn how to make a PR here. Moreover, if you are new to git or GitHub, you will find the Git book invaluable.
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.org
and sign up for an account. - Create a project. Your username will preface the URL and you may want to
append
-fabric
to ensure that you can distinguish between this and other docs that you need to create for other projects. So for example:YOURGITHUBID-fabric.readthedocs.io/en/latest
. - Click
Admin
, clickIntegrations
, clickAdd integration
, chooseGitHub incoming webhook
, then clickAdd integration
. - Fork the
fabric
repository. - From your fork, go to
Settings
in the upper right portion of the screen. - Click
Webhooks
. - Click
Add webhook
. - Add the ReadTheDocs”s URL into
Payload URL
. - Choose
Let me select individual events
:Pushes
、Branch or tag creation
、Branch or tag deletion
. - Click
Add webhook
.
Use 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 -s
option:
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 fabric
or fabric-docs-i18n
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 CODEOWNERS
files:
- US English
CODEOWNERS
and their maintainer GitHub IDs - International language
CODEOWNERS
and 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
_preamble.md
or_postscript.md
files undersrc/github.com/hyperledger/fabric/docs/wrappers
for the command. - To update the command help text, you need to edit the associated
.go
file for the command that is located under/fabric/internal/peer
. - Then, from the
fabric
folder, you need to run the commandmake help-docs
which generates the updated markdown files underdocs/source/commands
.
Remember that when you push the changes to GitHub, you need to include the
_preamble.md
, _postscript.md
or _.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/peer
for the new command and the associated help text. Seeinternal/peer/version
for a simple example to get started. - Add a section for your CLI command in
src/github.com/hyperledger/fabric/scripts/generateHelpDoc.sh
. - Create two new files under
/src/github.com/hyperledger/fabric/docs/wrappers
with the associated content:<command>_preamble.md
(Command name and syntax)<command>_postscript.md
(Example usage)
- Run
make help-docs
to 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.