github.com/defanghe/fabric@v2.1.1+incompatible/docs/README.md (about)

     1  # Documentation README
     2  
     3  ## Introduction
     4  
     5  This document contains information on how the Fabric documentation is
     6  built and published as well as a few conventions one should be aware of
     7  before making changes to the doc.
     8  
     9  The crux of the documentation is written in
    10  [reStructuredText](http://docutils.sourceforge.net/rst.html) which is
    11  converted to HTML using [Sphinx](http://www.sphinx-doc.org/en/stable/).
    12  The HTML is then published on http://hyperledger-fabric.readthedocs.io
    13  which has a hook so that any new content that goes into `docs/source`
    14  on the main repository will trigger a new build and publication of the
    15  doc.
    16  
    17  ## Conventions
    18  
    19  * Source files are in RST format and found in the `docs/source` directory.
    20  * The main entry point is index.rst, so to add something into the Table
    21    of Contents you would simply modify that file in the same manner as
    22    all of the other topics. It's very self-explanatory once you look at
    23    it.
    24  * Relative links should be used whenever possible. The preferred
    25    syntax for this is: :doc:\`anchor text <relativepath>\`
    26    <br/>Do not put the .rst suffix at the end of the filepath.
    27  * For non RST files, such as text files, MD or YAML files, link to the
    28    file on github, like this one for instance:
    29    https://github.com/hyperledger/fabric/blob/master/docs/README.md
    30  
    31  Notes: The above means we have a dependency on the github mirror
    32  repository. Relative links are unfortunately not working on github
    33  when browsing through a RST file.
    34  
    35  ## Setup
    36  
    37  Making any changes to the documentation will require you to test your
    38  changes by building the doc in a way similar to how it is done for
    39  production. There are two possible setups you can use to do so:
    40  setting up your own staging repo and publication website, or building
    41  the docs on your machine. The following sections cover both options:
    42  
    43  ### Setting up your own staging repo and publication website
    44  
    45  You can easily build your own staging repo following these steps:
    46  
    47  1. Go to http://readthedocs.org and sign up for an account.
    48  2. Create a project.
    49     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:
    50     `yourgithubid-fabric.readthedocs.io/en/latest`.
    51  3. Click `Admin`, click `Integrations`, click `Add integration`, choose `GitHub incoming webhook`,
    52     then click `Add integration`.
    53  4. Fork [Fabric on GitHub](https://github.com/hyperledger/fabric).
    54  5. From your fork, go to `Settings` in the upper right portion of the screen.
    55  6. Click `Webhooks`.
    56  7. Click `Add webhook`.
    57  8. Add the ReadTheDocs's URL into `Payload URL`.
    58  9. Choose `Let me select individual events`:`Pushes`、`Branch or tag creation`、`Branch or tag deletion`.
    59  10. Click `Add webhook`.
    60  
    61  Now anytime you modify or add documentation content to your fork, this
    62  URL will automatically get updated with your changes!
    63  
    64  ### Building the docs on your machine
    65  
    66  Here are the quick steps to achieve this on a local machine without
    67  depending on ReadTheDocs, starting from the main fabric
    68  directory. Note: you may need to adjust depending on your OS.
    69  
    70  Prereqs:
    71   - [Python 3.7](https://wiki.python.org/moin/BeginnersGuide/Download)
    72   - [Pipenv](https://docs.pipenv.org/en/latest/#install-pipenv-today)
    73  
    74  ```
    75  cd fabric/docs
    76  pipenv install
    77  pipenv shell
    78  make html
    79  ```
    80  
    81  This will generate all the html files in `docs/build/html` which you can
    82  then start browsing locally using your browser. Every time you make a
    83  change to the documentation you will of course need to rerun `make
    84  html`.
    85  
    86  In addition, if you'd like, you may also run a local web server with the following commands (or equivalent depending on your OS):
    87  
    88  ```
    89  sudo apt-get install apache2
    90  cd build/html
    91  sudo cp -r * /var/www/html/
    92  ```
    93  
    94  You can then access the html files at `http://localhost/index.html`.
    95  
    96  ## Updating Commands Reference topic
    97  
    98  Updating content in the [Commands Reference](https://hyperledger-fabric.readthedocs.io/en/latest/command_ref.html) topic requires additional steps. Because the information in the Commands Reference topic is generated content, you cannot simply update the associated markdown files.
    99  - Instead you need to update the `_preamble.md` or `_postscript.md` files under `src/github.com/hyperledger/fabric/docs/wrappers` for the command.
   100  - To update the command help text, you need to edit the associated `.go` file for the command that is located under `/fabric/internal/peer`.
   101  - Then, from the `fabric` folder, you need to run the command `make help-docs` which generates the updated markdown files under `docs/source/commands`. 
   102  
   103  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.
   104  
   105  ### Adding a new CLI command
   106  
   107  To add a new CLI command, perform the following steps:
   108  
   109  - Create a new folder under `/fabric/internal/peer` for the new command and the associated help text. See `internal/peer/version` for a simple example to get started.
   110  - Add a section for your CLI command in `src/github.com/hyperledger/fabric/scripts/generateHelpDoc.sh`.
   111  - Create two new files under `/src/github.com/hyperledger/fabric/docs/wrappers` with the associated content:
   112    - `<command>_preamble.md` (Command name and syntax)
   113    - `<command>_postscript.md` (Example usage)
   114  - Run `make help-docs` to generate the markdown content and push all of the changed files to GitHub.  
   115  
   116  <a rel="license" href="http://creativecommons.org/licenses/by/4.0/"><img alt="Creative Commons License" style="border-width:0" src="https://i.creativecommons.org/l/by/4.0/88x31.png" /></a><br />This work is licensed under a <a rel="license" href="http://creativecommons.org/licenses/by/4.0/">Creative Commons Attribution 4.0 International License</a>.