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/ -->