ドキュメントに貢献する

対象読者: Fabricドキュメントに貢献したい方.

この短いガイドでは、Fabricドキュメントの構成、構築、公開方法、およびFabricドキュメントの変更に役立ついくつかの規則について説明します。

このトピックでは、次の内容について説明します:

• はじめに
• リポジトリフォルダ構成
• 国際言語フォルダ構成
• ドキュメントを変更する
• ローカルマシン上のドキュメントをビルドする
• GitHub上のドキュメントをReadTheDocsを利用してビルドする
• 修正に対して承認をもらう
• コマンドリファレンスを変更する
• 新しいCLIコマンドを追加する

Introduction

Fabricドキュメントは、Markdownソース・ファイルとreStructuredTextソース・ファイルを組み合わせて作成されています。新規作成者は、どちらの形式でも使用できます。使い勝手が良いMarkdownを使用することをお勧めします。Pythonの経験がある場合は、rSTの方が扱い易いかもしれません。

ドキュメントのビルド・プロセスにおいて、ドキュメントのソース・ファイルはSphinxを使用してHTMLに変換されます。生成されたHTMLファイルは、その後、パブリックのドキュメントサイトに公開されます。ユーザーは、Fabricマニュアルの言語とバージョンの両方を選択できます。

例:

• 最新バージョンの英語（US）ドキュメント
• 最新バージョンの中国語ドキュメント
• バージョン2.2の英語（US）ドキュメント
• バージョン1.4の英語（US）ドキュメント

歴史的な理由から、英語（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

次の簡単な手順に従ってドキュメントをビルドします。

1. 適切なfabricまたはfabric-docs-i18nリポジトリのforkをGitHubアカウントに作成します。

2. 以下の必要なツールをインストールします。ご使用のOSによっては、調整が必要な場合があります:

   • Python 3.7
   • Pipenv

3. 英語（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ファイルに移動するだけです。

4. ここで、ファイルを少し変更し、ドキュメントを再構築して、変更が期待どおりであることを確認します。ドキュメントに変更を加えるたびに、当然のことながらmake htmlを再実行する必要があります。

5. 必要に応じて、次のコマンド(またはご使用のOS準じた同等の手順）でローカルWebサーバを立ち上げることもできます:

   sudo apt-get install apache2
   cd build/html
   sudo cp -r * /var/www/html/
   

   その後、http://localhost/index.htmlにあるhtmlファイルにアクセスできます。

6. PRの作成方法についてはこちらから学ぶことができます。さらに、gitやGitHubを初めて使う人にとっては、Git bookは非常に役に立ちます。

Building on GitHub

多くの場合、Fabricリポジトリからフォークしたあなた自身のレポジトリを使用してFabricドキュメントをビルドし、あなたが承認依頼を送信する前に他のユーザが変更を確認できるようにすることが有用です。次の手順では、ReadTheDocsを使用してこれを行う方法を示します。

1. http://readthedocs.orgにアクセスして、アカウントにサインアップします。
2. プロジェクトを作成します。ユーザ名はURLの前に挿入されます。他のプロジェクト用に作成するドキュメントと区別できるように、-fabricを追加することもできます。例えば以下の通りです: YOURGITHUBID-fabric.readthedocs.io/en/latest.
3. Adminをクリックし、Integrationsをクリックし、Add integrationをクリックし、GitHub incoming webhookを選択し、Add integrationをクリックします。
4. fabricリポジトリをフォークします。
5. フォークしたレポジトリから、画面右上のSettingsに移動します。
6. Webhooksをクリックします。
7. Add webhookをクリックします。
8. ReadTheDocsのURLをPayload URLに追加します。
9. Let me select individual events:Pushs、Branch or tag creation、Branch or tag deletionを選択します。
10. 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コマンドの翻訳は、現在、国際言語では使用できません。