github.com/osdi23p228/fabric@v0.0.0-20221218062954-77808885f5db/docs/source/docs_guide.md (about)

     1  # Contributing documentation
     2  
     3  **Audience**: Anyone who would like to contribute to the Fabric documentation.
     4  
     5  This short guide describes how the Fabric documentation is structured, built and
     6  published, as well as a few conventions that help writers make changes to the
     7  Fabric documentation.
     8  
     9  In this topic, we're going to cover:
    10  * [An introduction to the documentation](#introduction)
    11  * [Repository folder structure](#repository-folders)
    12  * [International language folder structure](#international-folders)
    13  * [Making documentation changes](#making-changes)
    14  * [Building the documentation on your local machine](#building-locally)
    15  * [Building the documentation on GitHub with ReadTheDocs](#building-on-github)
    16  * [Getting your change approved](#making-a-pr)
    17  * [Making a change to Commands Reference](#commands-reference-updates)
    18  * [Adding a new CLI command](#adding-a-new-cli-command)
    19  
    20  ## Introduction
    21  
    22  The Fabric documentation is written in a combination of
    23  [Markdown](https://www.markdownguide.org/) and
    24  [reStructuredText](http://docutils.sourceforge.net/rst.html) source files. As a
    25  new author you can use either format. We recommend that you use Markdown as an
    26  easy and powerful way to get started. If you have a background in Python, you
    27  may prefer to use rST.
    28  
    29  During the documentation build process, the documentation source files are
    30  converted to HTML using [Sphinx](http://www.sphinx-doc.org/en/stable/). The
    31  generated HTML files are subsequently published on the [public documentation
    32  website](http://hyperledger-fabric.readthedocs.io). Users can select both
    33  different languages and different versions of the Fabric documentation.
    34  
    35  For example:
    36  
    37    * [Latest version of US English](https://hyperledger-fabric.readthedocs.io/en/latest/)
    38    * [Latest version of Chinese](https://hyperledger-fabric.readthedocs.io/zh_CN/latest/)
    39    * [Version 2.2 of US English](https://hyperledger-fabric.readthedocs.io/en/release-2.2/)
    40    * [Version 1.4 of US English](https://hyperledger-fabric.readthedocs.io/en/release-1.4/)
    41  
    42  For historical reasons, the US English source files live in the main [Fabric
    43  repository](https://github.com/osdi23p228/fabric/), whereas all international
    44  language source files live in a single [Fabric i18n
    45  repository](https://github.com/hyperledger/fabric-docs-i18n). Different versions
    46  of the documentation are held within the appropriate GitHub release branch.
    47  
    48  ## Repository folders
    49  
    50  Both the US English and international language repositories have essentially the
    51  same structure, so let's start by examining the US English source files.
    52  
    53  All files relating to documentation reside within the `fabric/docs/` folder:
    54  
    55  ```bash
    56  fabric/docs
    57  ├── custom_theme
    58  ├── source
    59  │   ├── _static
    60  │   ├── _templates
    61  │   ├── commands
    62  │   ├── create_channel
    63  │   ├── dev-setup
    64  │   ├── developapps
    65  │   ├── diagrams
    66  │   ...
    67  │   ├── orderer
    68  │   ├── peers
    69  │   ├── policies
    70  │   ├── private-data
    71  │   ├── smartcontract
    72  │   ├── style-guides
    73  │   └── tutorial
    74  └── wrappers
    75  ```
    76  
    77  The most important folders is `source/` becuase it holds the source language
    78  files. The documentation build process uses the `make` command to convert these
    79  source files to HTML, which are stored in the dynamically created `build/html/`
    80  folder:
    81  
    82  ```bash
    83  fabric/docs
    84  ├── build
    85  │   ├── html
    86  ├── custom_theme
    87  ├── source
    88  │   ├── _static
    89  │   ├── _templates
    90  │   ├── commands
    91  │   ├── create_channel
    92  │   ├── dev-setup
    93  │   ├── developapps
    94  │   ├── diagrams
    95      ...
    96  ```
    97  
    98  Spend a little time navigating the [docs
    99  folder](https://github.com/osdi23p228/fabric/tree/master/docs) in the
   100  Hyperledger Fabric repository. Click on the following links to see how different
   101  source files map to their corresponding published topics.
   102  
   103  * [`/docs/source/index.rst`](https://raw.githubusercontent.com/hyperledger/fabric/master/docs/source/index.rst) maps to [Hyperledger Fabric title page](https://hyperledger-fabric.readthedocs.io/en/{RTD_TAG}/)
   104  
   105  * [`/docs/source/developapps/developing-applications.rst`](https://raw.githubusercontent.com/hyperledger/fabric/master/docs/source/developapps/developing_applications.rst)
   106    maps to [Developing
   107    applications](https://hyperledger-fabric.readthedocs.io/en/{RTD_TAG}/developapps/developing_applications.html)
   108  
   109  * [`/docs/source/peers/peers.md`](https://raw.githubusercontent.com/hyperledger/fabric/master/docs/source/peers/peers.md)
   110    maps to
   111    [Peers](https://hyperledger-fabric.readthedocs.io/en/{RTD_TAG}/peers/peers.html)
   112  
   113  We'll see how to make changes to these files a little later.
   114  
   115  ## International folders
   116  The international language repository,
   117  [`fabric-docs-i18n`](https://github.com/hyperledger/fabric-docs-i18n), follows
   118  almost exactly the same structure as the
   119  [`fabric`](https://github.com/hyperledger/fabric) repository which holds the US
   120  English files.  The difference is that each language is located within its own
   121  folder within `docs/locale/`:
   122  
   123  ```bash
   124  fabric-docs-i18n/docs
   125  └── locale
   126      ├── ja_JP
   127      ├── ml_IN
   128      ├── pt_BR
   129      └── zh_CN
   130  ```
   131  Examining any one of these folders shows a familiar structure:
   132  ```bash
   133  locale/ml_IN
   134  ├── custom_theme
   135  ├── source
   136  │   ├── _static
   137  │   ├── _templates
   138  │   ├── commands
   139  │   ├── dev-setup
   140  │   ├── developapps
   141  │   ├── diagrams
   142  │   ...
   143  │   ├── orderer
   144  │   ├── peers
   145  │   ├── policies
   146  │   ├── private-data
   147  │   ├── smartcontract
   148  │   ├── style-guides
   149  │   └── tutorial
   150  └── wrappers
   151  ```
   152  
   153  As we'll soon see, the similarity of the international language and US English
   154  folder structures means that the same instructions and commands can be used to
   155  manage different language translations.
   156  
   157  Again, spend some time examining the [international language
   158  repository](https://github.com/hyperledger/fabric-docs-i18n).
   159  
   160  ## Making changes
   161  
   162  To update the documentation, you simply change one or more language source files
   163  in a local git feature branch, build the changes locally to check they're OK,
   164  and submit a Pull request (PR) to merge your branch with the appropriate Fabric
   165  repository branch. Once your PR has been reviewed and approved by the appropriate
   166  maintainers for the language, it will be merged into the repository and become
   167  part of the published documentation. It really is that easy!
   168  
   169  As well as being polite, it's a really good idea to test any documentation
   170  changes before you request to include it in a repository. The following sections
   171  show you how to:
   172  
   173  * Build and review a documentation change on your own machine.
   174  
   175  
   176  * Push these changes to your GitHub repository fork where they can populate your
   177    personal [ReadTheDocs](https://readthedocs.org/) publication website for
   178    collaborators to review.
   179  
   180  
   181  * Submit your documentation PR for inclusion in the `fabric` or
   182    `fabric-docs-i18n` repository.
   183  
   184  ## Building locally
   185  
   186  Use these simple steps to build the documentation.
   187  
   188  1. Create a fork of the appropriate
   189  [`fabric`](https://github.com/hyperledger/fabric) or
   190  [`fabric-i18n`](https://github.com/hyperledger/fabric-docs-i18n) repository to
   191  your GitHub account.
   192  
   193  2. Install the following prerequisites; you may need to adjust depending on your
   194     OS:
   195  
   196     * [Python 3.7](https://wiki.python.org/moin/BeginnersGuide/Download)
   197     * [Pipenv](https://docs.pipenv.org/en/latest/#install-pipenv-today)
   198  
   199  3. For US English:
   200     ```bash
   201     cd $HOME/git
   202     git clone git@github.com:hyperledger/fabric.git
   203     cd fabric/docs
   204     pipenv install
   205     pipenv shell
   206     make html
   207     ```
   208  
   209     For Malayalam (for example):
   210     ```bash
   211     cd $HOME/git
   212     git clone git@github.com:hyperledger/fabric-docs-i18n.git
   213     cd fabric-docs-18n/docs/locale/ml_IN
   214     pipenv install
   215     pipenv shell
   216     make -e SPHINXOPTS="-D language='ml'" html
   217     ```
   218  
   219     The `make` command generates documentation html files in the `build/html/`
   220     folder which you can now view locally; simply navigate your browser to the
   221     `build/html/index.html` file.
   222  
   223  4. Now make a small change to a file, and rebuild the documentation to verify
   224     that your change was as expected. Every time you make a change to the
   225     documentation you will of course need to rerun `make html`.
   226  
   227  5. If you'd like, you may also run a local web server with the following
   228     commands (or equivalent depending on your OS):
   229  
   230     ```bash
   231     sudo apt-get install apache2
   232     cd build/html
   233     sudo cp -r * /var/www/html/
   234     ```
   235  
   236     You can then access the html files at `http://localhost/index.html`.
   237  
   238  6. You can learn how to make a PR [here](./github/github.html). Moreover, if you
   239     are new to git or GitHub, you will find the [Git
   240     book](https://git-scm.com/book/en/v2) invaluable.
   241  
   242  ## Building on GitHub
   243  
   244  It is often helpful to use your fork of the Fabric repository to build the
   245  Fabric documentation so that others can review your changes before you submit
   246  them for approval. The following instructions show you how to use ReadTheDocs to
   247  do this.
   248  
   249  1. Go to [`http://readthedocs.org`](http://readthedocs.org) and sign up for an
   250     account.
   251  2. Create a project. Your username will preface the URL and you may want to
   252     append `-fabric` to ensure that you can distinguish between this and other
   253     docs that you need to create for other projects. So for example:
   254     `YOURGITHUBID-fabric.readthedocs.io/en/latest`.
   255  3. Click `Admin`, click `Integrations`, click `Add integration`, choose `GitHub
   256     incoming webhook`, then click `Add integration`.
   257  4. Fork the [`fabric`](https://github.com/hyperledger/fabric) repository.
   258  5. From your fork, go to `Settings` in the upper right portion of the screen.
   259  6. Click `Webhooks`.
   260  7. Click `Add webhook`.
   261  8. Add the ReadTheDocs's URL into `Payload URL`.
   262  9. Choose `Let me select individual events`:`Pushes`、`Branch or tag creation`、
   263     `Branch or tag deletion`.
   264  10. Click `Add webhook`.
   265  
   266  Use `fabric-docs-i18n` instead of `fabric` in the above instructions if you're
   267  building an international language translation.
   268  
   269  Now, anytime you modify or add documentation content to your fork, this URL will
   270  automatically get updated with your changes!
   271  
   272  ## Making a PR
   273  
   274  You can submit your PR for inclusion using the following
   275  [instructions](./github/github.html).
   276  
   277  Pay special attention to signing your commit with the `-s` option:
   278  
   279  ```bash
   280  git commit -s -m "My Doc change"
   281  ```
   282  
   283  This states that your changes conform to the [Developer Certificate of
   284  Origin](https://en.wikipedia.org/wiki/Developer_Certificate_of_Origin).
   285  
   286  Before your PR can be included in the appropriate `fabric` or `fabric-docs-i18n`
   287  repository, it must be approved by an appropriate maintainer. For example, a
   288  Japanese translation must be approved by a Japanese maintainer, and so on. You
   289  can find the maintainers listed in the following `CODEOWNERS` files:
   290  
   291  * US English
   292    [`CODEOWNERS`](https://github.com/osdi23p228/fabric/blob/master/CODEOWNERS)
   293    and their [maintainer GitHub
   294    IDs](https://github.com/orgs/hyperledger/teams/fabric-core-doc-maintainers)
   295  * International language
   296    [`CODEOWNERS`](https://github.com/hyperledger/fabric-docs-i18n/blob/master/CODEOWNERS)
   297    and their [maintainer GitHub
   298    IDs](https://github.com/orgs/hyperledger/teams/fabric-contributors)
   299  
   300  Both language repositories have a GitHub webhook defined so that, once approved,
   301  your newly merged content in the `docs/` folder will trigger an automatic build
   302  and publication of the updated documentation.
   303  
   304  ## Commands Reference updates
   305  
   306  Updating content in the [Commands
   307  Reference](https://hyperledger-fabric.readthedocs.io/en/latest/command_ref.html)
   308  topic requires additional steps. Because the information in the Commands
   309  Reference topic is generated content, you cannot simply update the associated
   310  markdown files.
   311  - Instead you need to update the `_preamble.md` or `_postscript.md` files under
   312    `src/github.com/osdi23p228/fabric/docs/wrappers` for the command.
   313  - To update the command help text, you need to edit the associated `.go` file
   314    for the command that is located under `/fabric/internal/peer`.
   315  - Then, from the `fabric` folder, you need to run the command `make help-docs`
   316    which generates the updated markdown files under `docs/source/commands`.
   317  
   318  Remember that when you push the changes to GitHub, you need to include the
   319  `_preamble.md`, `_postscript.md` or `_.go` file that was modified as well as the
   320  generated markdown file.
   321  
   322  This process only applies to English language translations. Command Reference
   323  translation is currently not possible in international languages.
   324  
   325  ## Adding a new CLI command
   326  
   327  To add a new CLI command, perform the following steps:
   328  
   329  - Create a new folder under `/fabric/internal/peer` for the new command and the
   330    associated help text. See `internal/peer/version` for a simple example to get
   331    started.
   332  - Add a section for your CLI command in
   333    `src/github.com/osdi23p228/fabric/scripts/generateHelpDoc.sh`.
   334  - Create two new files under `/src/github.com/osdi23p228/fabric/docs/wrappers`
   335    with the associated content:
   336    - `<command>_preamble.md` (Command name and syntax)
   337    - `<command>_postscript.md` (Example usage)
   338  - Run `make help-docs` to generate the markdown content and push all of the
   339    changed files to GitHub.
   340  
   341  This process only applies to English language translations. CLI
   342  command translation is currently not possible in international languages.
   343  
   344  <!--- Licensed under Creative Commons Attribution 4.0 International License
   345  https://creativecommons.org/licenses/by/4.0/ -->