ドキュメントに貢献する¶
対象読者: Fabricドキュメントに貢献したい方.
この短いガイドでは、Fabricドキュメントの構成、構築、公開方法、およびFabricドキュメントの変更に役立ついくつかの規則について説明します。
このトピックでは、次の内容について説明します:
- はじめに
- リポジトリフォルダ構成
- 国際言語フォルダ構成
- ドキュメントを変更する
- ローカルマシン上のドキュメントをビルドする
- GitHub上のドキュメントをReadTheDocsを利用してビルドする
- 修正に対して承認をもらう
- コマンドリファレンスを変更する
- 新しいCLIコマンドを追加する
Introduction¶
Fabricドキュメントは、Markdownソース・ファイルとreStructuredTextソース・ファイルを組み合わせて作成されています。新規作成者は、どちらの形式でも使用できます。使い勝手が良いMarkdownを使用することをお勧めします。Pythonの経験がある場合は、rSTの方が扱い易いかもしれません。
ドキュメントのビルド・プロセスにおいて、ドキュメントのソース・ファイルはSphinxを使用してHTMLに変換されます。生成されたHTMLファイルは、その後、パブリックのドキュメントサイトに公開されます。ユーザーは、Fabricマニュアルの言語とバージョンの両方を選択できます。
例:
歴史的な理由から、英語(US)ドキュメントのソース・ファイルはメインのFabricリポジトリで管理されますが、国際言語向けドキュメントのソース・ファイルはすべて1つのFabric i18nリポジトリで管理されます。ドキュメントの異なるバージョンは、適切なGitHubリリースブランチに保持されています。
Repository folders¶
英語(US)ドキュメントのリポジトリと国際言語向けドキュメントのリポジトリは基本的に同じ構成を持つため、まず英語(US)ドキュメントのソースファイルを見ていくところからスタートします。
ドキュメントに関連するすべてのファイルは、fabric/docs/
フォルダ内にあります:
fabric/docs
├── custom_theme
├── source
│ ├── _static
│ ├── _templates
│ ├── commands
│ ├── create_channel
│ ├── dev-setup
│ ├── developapps
│ ├── diagrams
│ ...
│ ├── orderer
│ ├── peers
│ ├── policies
│ ├── private-data
│ ├── smartcontract
│ ├── style-guides
│ └── tutorial
└── wrappers
最も重要なフォルダは、ソースとなる言語ファイルが格納されている source/
フォルダです。ドキュメントのビルドプロセスでは、make
コマンドを使用して、このソースファイルをHTMLに変換し、動的に作成されるbuild/html/
フォルダに格納します:
fabric/docs
├── build
│ ├── html
├── custom_theme
├── source
│ ├── _static
│ ├── _templates
│ ├── commands
│ ├── create_channel
│ ├── dev-setup
│ ├── developapps
│ ├── diagrams
...
Hyperledger Fabricリポジトリ内のdocsフォルダ内を見るのに少し時間を割いてみてください。次のリンクをクリックすると、ソースファイルが対応する公開トピックにどのようにマッピングされているか確認できます。
/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
これらのファイルの変更方法については、後ほど説明します。
International folders¶
国際言語リポジトリfabric-docs-i18n
は、英語(US)ファイルを保持するfabric
リポジトリとほぼ同じ構成に従います。違いは、各言語のファイルがdocs/locale/
の個別のフォルダに格納されている点です:
fabric-docs-i18n/docs
└── locale
├── ja_JP
├── ml_IN
├── pt_BR
└── zh_CN
これらのフォルダのどれを見ても、既に馴染みのある構成であることが分かります:
locale/ml_IN
├── custom_theme
├── source
│ ├── _static
│ ├── _templates
│ ├── commands
│ ├── dev-setup
│ ├── developapps
│ ├── diagrams
│ ...
│ ├── orderer
│ ├── peers
│ ├── policies
│ ├── private-data
│ ├── smartcontract
│ ├── style-guides
│ └── tutorial
└── wrappers
後で説明しますが、多言語と英語(US)のフォルダ構成が似ているため、同じ手順とコマンドを使用してさまざまな言語の翻訳を管理できます。
ここでも、国際言語リポジトリを見るのに少し時間を割いてみてください。
Making changes¶
ドキュメントを更新するには、ローカルのgit作業用ブランチ上でで1つ以上の言語ソースファイルを変更し、ローカルで変更をビルドして問題がないことを確認し、Pull request(PR)を送ってブランチを適切なFabricリポジトリのブランチにマージします。あなたのPRがその言語の適切なメンテナによってレビューされ、承認されると、それはリポジトリにマージされ、公開されたドキュメントの一部になります。本当に簡単です!
ドキュメントの変更をリポジトリに取り込むよう要求する前に、その変更をテストすることは、マナーであるというだけでなく、本当に大事なことです。次の節では、以下の方法について説明します:
- 自分のマシンでドキュメントの変更をビルドして確認します。
- これらの変更をフォークしたあなたのGitHubリポジトリにプッシュして、あなた個人のReadTheDocsWebサイトに反映することで共同作業者がレビューできるようになります。
fabric
またはfabric-docs-i18n
リポジトリに取り込むドキュメントのPRを送信します。
Building locally¶
次の簡単な手順に従ってドキュメントをビルドします。
適切な
fabric
またはfabric-docs-i18n
リポジトリのforkをGitHubアカウントに作成します。以下の必要なツールをインストールします。ご使用のOSによっては、調整が必要な場合があります:
英語(US)の場合:
cd $HOME/git git clone git@github.com:hyperledger/fabric.git cd fabric/docs pipenv install pipenv shell make html
マラヤーラム語の場合(例):
cd $HOME/git git clone git@github.com:hyperledger/fabric-docs-i18n.git cd fabric-docs-18n/docs/locale/ml_IN pipenv install pipenv shell make -e SPHINXOPTS="-D language='ml'" html
make
コマンドを実行すると、build/html/
フォルダにドキュメントのhtmlファイルが生成されます。このファイルはローカルで表示できます。ブラウザでbuild/html/index.html
ファイルに移動するだけです。ここで、ファイルを少し変更し、ドキュメントを再構築して、変更が期待どおりであることを確認します。ドキュメントに変更を加えるたびに、当然のことながら
make html
を再実行する必要があります。必要に応じて、次のコマンド(またはご使用のOS準じた同等の手順)でローカルWebサーバを立ち上げることもできます:
sudo apt-get install apache2 cd build/html sudo cp -r * /var/www/html/
その後、
http://localhost/index.html
にあるhtmlファイルにアクセスできます。PRの作成方法についてはこちらから学ぶことができます。さらに、gitやGitHubを初めて使う人にとっては、Git bookは非常に役に立ちます。
Building on GitHub¶
多くの場合、Fabricリポジトリからフォークしたあなた自身のレポジトリを使用してFabricドキュメントをビルドし、あなたが承認依頼を送信する前に他のユーザが変更を確認できるようにすることが有用です。次の手順では、ReadTheDocsを使用してこれを行う方法を示します。
http://readthedocs.org
にアクセスして、アカウントにサインアップします。- プロジェクトを作成します。ユーザ名はURLの前に挿入されます。他のプロジェクト用に作成するドキュメントと区別できるように、
-fabric
を追加することもできます。例えば以下の通りです:YOURGITHUBID-fabric.readthedocs.io/en/latest
. Admin
をクリックし、Integrations
をクリックし、Add integration
をクリックし、GitHub incoming webhook
を選択し、Add integration
をクリックします。fabric
リポジトリをフォークします。- フォークしたレポジトリから、画面右上の
Settings
に移動します。 Webhooks
をクリックします。Add webhook
をクリックします。- ReadTheDocsのURLを
Payload URL
に追加します。 Let me select individual events
:Pushs
、Branch or tag creation
、Branch or tag deletion
を選択します。Add webhook
をクリックします。
国際言語翻訳をビルドする場合は、上記の手順でfabric
の代わりにfabric-docs-i18n
を使用します。
ドキュメントの内容をあなたのフォーク上で変更または追加するたびに、このURL上の内容が自動的にあなたの修正で更新されます!
Making a PR¶
次の手順に従って、修正取り込みのPRを送信することができます。
-s
オプションを使用してコミットに署名することに特に注意してください。
git commit -s -m "My Doc change"
これは、変更がDeveloper Certificate of Originに準拠していることを示します。
PRを適切なfabric
またはfabric-docs-i18n
リポジトリに含めるには、適切なメンテナの承認が必要です。たとえば、日本語の翻訳は日本語のメンテナの承認が必要です。メンテナは、次のCODEOWNERS
ファイルにリストされています。
- US English
CODEOWNERS
and their maintainer GitHub IDs - International language
CODEOWNERS
and their maintainer GitHub IDs
どちらの言語リポジトリにもGitHubのwebhookが定義されているので、いったん承認されると、docs/
フォルダに新しくマージされたコンテンツが自動的にビルドされ、更新されたドキュメントが発行されます。
Commands Reference updates¶
コマンドリファレンストピックの内容を更新するには、追加の手順が必要です。コマンドリファレンストピックの情報は生成されたコンテンツであるため、関連するMarkdownファイルを単純に更新することはできません。
- 代わりに、
src/github.com/hyperledger/fabric/docs/wrappers
の下にある、このコマンドの_preamble.md
または_postscript.md
ファイルを更新する必要があります。 - コマンドのヘルプテキストを更新するには、
/fabric/internal/peer
の下にあるコマンドに関連付けられた.go
ファイルを編集する必要があります。 - 次に
fabric
フォルダ内でmake help-docs
コマンドを実行し、docs/source/commands
の下に更新されたMarkdownファイルを生成します。
GitHubに変更をプッシュするときは、生成されたMarkdownファイルと同様に、変更された_preamble.md
、_postscript.md
、_.go
ファイルを含める必要があることに注意してください。
このプロセスは、英語の翻訳にのみ適用されます。現在、コマンドリファレンスの翻訳は、国際言語向けには使用できません。
Adding a new CLI command¶
新しいCLIコマンドを追加するには、次の手順を実行します:
- 新しいコマンドと関連するヘルプテキストのために、
/fabric/internal/peer
の下に新しいフォルダを作成します。新しいコマンド追加を始めるための簡単な例については、internal/peer/version
を参照してください。 - あなたが追加したCLIコマンドのセクションを
src/github.com/hyperledger/fabric/scripts/generateHelpDoc.sh
に追加します。 /src/github.com/hyperledger/fabric/docs/wrappers
の下に、関連するコンテンツとともに2つの新しいファイルを作成します:<command>_preamble.md
(コマンド名と構文)<command>_postscript.md
(使用例)
make help-docs
を実行してMarkdownコンテンツを生成し、変更されたすべてのファイルをGitHubにプッシュします。
このプロセスは、英語の翻訳にのみ適用されます。CLIコマンドの翻訳は、現在、国際言語では使用できません。