From 347899efab13f45ce464fe5dcc2e95e043a1cf70 Mon Sep 17 00:00:00 2001 From: Arnaud J Le Hors Date: Wed, 3 May 2017 10:00:39 +0200 Subject: [PATCH] [FAB-3201] Fix many of the broken links in the doc This change fixes most broken links. Commit #1 and #2 Fixes several broken links. Commit #3 Remove note linking to document that no longer exists in reponse to Tracy's comment. Commit #4 Do the above for good. Commit #5 and #6 Fixes many of the remaining broken links, based on the w3c and xenu link checkers. Before this change, with Xenu we have: 25 broken link(s) reported 3 bad local link(s) reported After this change, we have: 4 broken link(s) reported 0 bad local link(s) reported Commit #7 Fixes Tracy's comments on latest commit. [ci-skip] Change-Id: I57d942c19f0904548fc6298408c459940c5d33a8 Signed-off-by: Arnaud J Le Hors --- docs/source/CONTRIBUTING.rst | 32 +++++++++++----------- docs/source/Gerrit/best-practices.rst | 4 +-- docs/source/Gerrit/changes.rst | 4 +-- docs/source/Gerrit/gerrit.rst | 18 ++++++------ docs/source/Setup/Chaincode-setup.rst | 13 +++------ docs/source/Setup/JAVAChaincode.rst | 5 ++-- docs/source/Setup/ca-setup.rst | 2 +- docs/source/architecture.rst | 30 ++++++++++---------- docs/source/configtx.rst | 6 ++-- docs/source/license.rst | 3 +- docs/source/questions.rst | 2 +- docs/source/starter/fabric-starter-kit.rst | 3 +- docs/source/status.rst | 2 +- examples/dchackfest/samples/e2e/README.rst | 3 +- 14 files changed, 60 insertions(+), 67 deletions(-) diff --git a/docs/source/CONTRIBUTING.rst b/docs/source/CONTRIBUTING.rst index 93c5bf76467..2dbb9d3ae7d 100644 --- a/docs/source/CONTRIBUTING.rst +++ b/docs/source/CONTRIBUTING.rst @@ -12,8 +12,8 @@ Getting a Linux Foundation account ---------------------------------- In order to participate in the development of the Hyperledger Fabric -project, you will need a `Linux Foundation -account `__. You will need to use your LF ID to +project, you will need a :doc:`Linux Foundation +account `. You will need to use your LF ID to access to all the Hyperledger community development tools, including `Gerrit `__, `Jira `__ and the @@ -25,7 +25,7 @@ Setting up your SSH key For Gerrit, before you can submit any change set for review, you will need to register your public SSH key. Login to `Gerrit `__ with your -`LFID `__, and click on your name in the upper +:doc:`LFID `, and click on your name in the upper right-hand corner of your browser window and then click 'Settings'. In the left-hand margin, you should see a link for 'SSH Public Keys'. Copy-n-paste your `public SSH @@ -87,21 +87,21 @@ Working with a local clone and Gerrit We are using `Gerrit `__ to manage code contributions. If you are unfamiliar, please review this -`document `__ before proceeding. +:doc:`document ` before proceeding. After you have familiarized yourself with ``Gerrit``, and maybe played around with the ``lf-sandbox`` `project `__, you should be ready to set up your local development -`environment `__. +:doc:`environment `. -Next, try `building the project `__ in your local +Next, try :doc:`building the project ` in your local development environment to ensure that everything is set up correctly. -`Logging control `__ describes how to tweak +:doc:`Logging control ` describes how to tweak the logging levels of various components within the Fabric. Finally, -every source file needs to include a `license -header `__: modified to include a copyright +every source file needs to include a `license header +`__: modified to include a copyright statement for the principle author(s). What makes a good change request? @@ -185,8 +185,8 @@ remediate the merge conflicts. Coding guidelines ----------------- -Be sure to check out the language-specific `style -guides `__ before making any changes. This +Be sure to check out the language-specific :doc:`style +guides ` before making any changes. This will ensure a smoother review. Communication @@ -202,7 +202,7 @@ list `__. Maintainers ----------- -The project's `maintainers `__ are responsible for +The project's :doc:`maintainers ` are responsible for reviewing and merging all patches submitted for review and they guide the over-all technical direction of the project within the guidelines established by the Hyperledger Project's Technical Steering Committee @@ -218,7 +218,7 @@ designate an initial set of maintainers that will be approved by the top-level project's existing maintainers when the project is first approved. The project's maintainers will, from time-to-time, consider adding or removing a maintainer. An existing maintainer can submit a -change set to the `MAINTAINERS.rst `__ file. If there are +change set to the :doc:`MAINTAINERS.rst ` file. If there are less than eight maintainers, a majority of the existing maintainers on that project are required to merge the change set. If there are more than eight existing maintainers, then if five or more of the maintainers @@ -232,13 +232,13 @@ Legal stuff ----------- **Note:** Each source file must include a license header for the Apache -Software License 2.0. A template of that header can be found -`here `__. +Software License 2.0. See the template of the `license header +`__. We have tried to make it as easy as possible to make contributions. This applies to how we handle the legal aspects of contribution. We use the same approach—the `Developer's Certificate of Origin 1.1 -(DCO) `__—that the Linux® Kernel +(DCO) `__—that the Linux® Kernel `community `__ uses to manage code contributions. diff --git a/docs/source/Gerrit/best-practices.rst b/docs/source/Gerrit/best-practices.rst index c8385c9797b..dec0bdae7b3 100644 --- a/docs/source/Gerrit/best-practices.rst +++ b/docs/source/Gerrit/best-practices.rst @@ -41,7 +41,7 @@ text at 72 chars/line. | Jira: FAB-100 | Change-Id: LONGHEXHASH -| Signed-off-by: Your Name your.email@example.org +| Signed-off-by: Your Name your.email\@example.org | AnotherExampleHeader: An Example of another Value The Gerrit server provides a precommit hook to autogenerate the @@ -148,7 +148,7 @@ Finding Available Topics $ ssh -p 29418 gerrit.hyperledger.org gerrit query \ status:open project:fabric branch:master \ | grep topic: | sort -u -- `gerrit.hyperledger.org <>`__ Is the current URL where the project is +- `gerrit.hyperledger.org `__ Is the current URL where the project is hosted. - *status* Indicates the topic's current status: open , merged, abandoned, draft, merge conflict. diff --git a/docs/source/Gerrit/changes.rst b/docs/source/Gerrit/changes.rst index 56abbcf244e..90311b5eff4 100644 --- a/docs/source/Gerrit/changes.rst +++ b/docs/source/Gerrit/changes.rst @@ -10,7 +10,7 @@ Change Requirements This section contains guidelines for submitting code changes for review. For more information on how to submit a change using Gerrit, please see -`Gerrit `__. +:doc:`Gerrit `. Changes are submitted as Git commits. Each commit must contain: @@ -31,7 +31,7 @@ Informationally, ``commit messages`` must include: - **why** you chose that approach, and - **how** you know it works -- for example, which tests you ran. -Commits must `build cleanly <../dev-setup/build.md>`__ when applied in +Commits must :doc:`build cleanly <../dev-setup/build>` when applied in top of each other, thus avoiding breaking bisectability. Each commit must address a single identifiable issue and must be logically self-contained. diff --git a/docs/source/Gerrit/gerrit.rst b/docs/source/Gerrit/gerrit.rst index eb6cc7da3ae..2ce2222f61c 100644 --- a/docs/source/Gerrit/gerrit.rst +++ b/docs/source/Gerrit/gerrit.rst @@ -19,8 +19,8 @@ Gerrit assigns the following roles to users: - **Builders**: (e.g. Jenkins) May use the build automation infrastructure to verify the change. -Maintainers should be familiar with the `review -process `__. However, anyone is welcome to (and +Maintainers should be familiar with the :doc:`review +process `. However, anyone is welcome to (and encouraged!) review changes, and hence may find that document of value. Git-review @@ -48,7 +48,7 @@ A comprehensive walk-through of Gerrit is beyond the scope of this document. There are plenty of resources available on the Internet. A good summary can be found `here `__. We have also -provided a set of `Best Practices `__ that you may +provided a set of :doc:`Best Practices ` that you may find helpful. Working with a local clone of the repository @@ -72,7 +72,7 @@ To work on something, whether a new feature or a bugfix: **Note:** if you are cloning the fabric project repository, you will want to clone it to the ``$GOPATH/src/github.com/hyperledger`` directory so that it will build, and so that you can use it with the Vagrant -`development environment <../dev-setup/devenv.md>`__. +:doc:`development environment <../dev-setup/devenv>`. 4. Create a descriptively-named branch off of your cloned repository @@ -82,7 +82,7 @@ so that it will build, and so that you can use it with the Vagrant git checkout -b issue-nnnn 5. Commit your code. For an in-depth discussion of creating an effective - commit, please read `this document `__. + commit, please read :doc:`this document on submitting changes `. :: @@ -99,8 +99,9 @@ Submitting a Change ------------------- Currently, Gerrit is the only method to submit a change for review. -**Please review the `guidelines `__ for making and -submitting a change**. + +**Note:** Please review the :doc:`guidelines ` for making and +submitting a change. Use git review ~~~~~~~~~~~~~~ @@ -130,8 +131,7 @@ and then repeat the ``git review`` command. Not Use git review ~~~~~~~~~~~~~~~~~~ -Directions for building the source code can be found -`here <../dev-setup/build.md>`__. +See the :doc:`directions for building the source code <../dev-setup/build>`. When a change is ready for submission, Gerrit requires that the change be pushed to a special branch. The name of this special branch contains diff --git a/docs/source/Setup/Chaincode-setup.rst b/docs/source/Setup/Chaincode-setup.rst index 3f4108fecdf..64de7c16d59 100644 --- a/docs/source/Setup/Chaincode-setup.rst +++ b/docs/source/Setup/Chaincode-setup.rst @@ -15,13 +15,10 @@ chaincode as a Docker container. The following instructions apply to *developing* chaincode in Go or Java. They do not apply to running in a production environment. However, -if *developing* chaincode in Java, please see the `Java chaincode -setup `__ +if *developing* chaincode in Java, please see the :doc:`Java chaincode +setup ` instructions first, to be sure your environment is properly configured. -**Note:** We have added support for `System -chaincode `__. - Choices ------- @@ -29,8 +26,7 @@ Once again, you have the choice of using one of the following approaches: - `Option 1 <#option-1-vagrant-development-environment>`__ using the - **Vagrant** `development - environment `__ + **Vagrant** :doc:`development environment <../dev-setup/devenv>` that is used for developing the fabric itself - `Option 2 <#option-2-docker-for-mac-or-windows>`__ using Docker for Mac or Windows @@ -328,8 +324,7 @@ when security is enabled <#removing-temporary-files-when-security-is-enabled>`__ to learn how to clean up the temporary files. -See the `logging -control `__ +See the :doc:`logging control ` reference for information on controlling logging output from the ``peer`` and chaincodes. diff --git a/docs/source/Setup/JAVAChaincode.rst b/docs/source/Setup/JAVAChaincode.rst index e8db20dcfd2..ee120399e50 100644 --- a/docs/source/Setup/JAVAChaincode.rst +++ b/docs/source/Setup/JAVAChaincode.rst @@ -1,9 +1,8 @@ Java chaincode -------------- -Note: This guide generally assumes you have followed the Chaincode -development environment setup tutorial -`here `__. +Note: This guide generally assumes you have followed the :doc:`Chaincode +development environment setup tutorial `. To get started developing Java chaincode ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/source/Setup/ca-setup.rst b/docs/source/Setup/ca-setup.rst index 6ccd4ec9240..707bef029de 100644 --- a/docs/source/Setup/ca-setup.rst +++ b/docs/source/Setup/ca-setup.rst @@ -50,7 +50,7 @@ Table of Contents 6. `Fabric CA Client`_ - 1. `Enrolling the bootstrap user`_ + 1. `Enrolling the bootstrap identity`_ 2. `Registering a new identity`_ 3. `Enrolling a peer identity`_ 4. `Reenrolling an identity`_ diff --git a/docs/source/architecture.rst b/docs/source/architecture.rst index 85bb663a0a0..6868e42e2a2 100644 --- a/docs/source/architecture.rst +++ b/docs/source/architecture.rst @@ -4,16 +4,16 @@ delivering accountability, transparency, and efficiencies unmatched by other blockchain or DLT technology. Hyperledger Fabric implements a specific type of -`permissioned `__ `blockchain -network `__ on which members can track, +:doc:`permissioned ` :doc:`blockchain +network ` on which members can track, exchange and interact with digitized assets using -`transactions `__ that are governed by smart -contracts - what we call `chaincode `__ - in a +:doc:`transactions ` that are governed by smart +contracts - what we call :doc:`chaincode ` - in a secure and robust manner while enabling -`participants `__ in the network to interact +:doc:`participants ` in the network to interact in a manner that ensures that their transactions and data can be restricted to an identified subset of network participants - something -we call a `channel `__. +we call a :doc:`channel `. The blockchain network supports the ability for members to establish shared ledgers that contain the source of truth about those digitized @@ -28,31 +28,31 @@ Hyperledger Fabric also offers a certificate authority service, *fabric-ca* but, you may substitute that with your own. All peer nodes maintain the ledger/state by committing transactions. In -that role, the peer is called a `committer `__. +that role, the peer is called a :doc:`committer `. Some peers are also responsible for simulating transactions by executing chaincodes (smart contracts) and endorsing the result. In that role the -peer is called an `endorser `__. A peer may be an +peer is called an :doc:`endorser `. A peer may be an endorser for certain types of transactions and just a ledger maintainer (committer) for others. -The `orderers `__ consent on the order of +The :doc:`orderers ` consent on the order of transactions in a block to be committed to the ledger. In common blockchain architectures (including earlier versions of the Hyperledger Fabric) the roles played by the peer and orderer nodes were unified (cf. validating peer in Hyperledger Fabric v0.6). The orderers also play a fundamental role in the creation and management of channels. -Two or more `participants `__ may create and +Two or more :doc:`participants ` may create and join a channel, and begin to interact. Among other things, the policies governing the channel membership and chaincode lifecycle are specified at the time of channel creation. Initially, the members in a channel agree on the terms of the chaincode that will govern the transactions. -When consensus is reached on the `proposal `__ to +When consensus is reached on the :doc:`proposal ` to deploy a given chaincode (as governed by the life cycle policy for the channel), it is committed to the ledger. -Once the chaincode is deployed to the peer nodes in the channel, `end -users `__ with the right privileges can propose +Once the chaincode is deployed to the peer nodes in the channel, :doc:`end +users ` with the right privileges can propose transactions on the channel by using one of the language-specific client SDKs to invoke functions on the deployed chaincode. @@ -100,5 +100,5 @@ Some key capabilities of Hyperledger Fabric include: required levels of trust and verification across nodes for optimization. -For a deeper dive into the details, please visit `this -document `__. +For a deeper dive into the details, please visit :doc:`this +document `. diff --git a/docs/source/configtx.rst b/docs/source/configtx.rst index 9bc20f72a3f..6c91f87334d 100644 --- a/docs/source/configtx.rst +++ b/docs/source/configtx.rst @@ -71,9 +71,9 @@ policies. It is defined as follows: string mod_policy = 5; } -Because ``ConfigGroup`` is a recursive structure, consider an example -hierarchical arrangement of ``ConfigGroup``s (expressed for clarity in -golang notation). +Because ``ConfigGroup`` is a recursive structure, it has hierarchical +arrangement. The following example is expressed for clarity in golang +notation. :: diff --git a/docs/source/license.rst b/docs/source/license.rst index 86bb7eb5a81..df0837491d2 100644 --- a/docs/source/license.rst +++ b/docs/source/license.rst @@ -2,4 +2,5 @@ License ======== The Hyperledger Project uses the `Apache License Version -2.0 `__ software license. +2.0 `__ software +license. diff --git a/docs/source/questions.rst b/docs/source/questions.rst index 038e6c31027..24381011525 100644 --- a/docs/source/questions.rst +++ b/docs/source/questions.rst @@ -10,5 +10,5 @@ use If you need help finding things, please don't hesitate to send a note to the `mailing list `__, -or ask on `RocketChat <(https://chat.hyperledger.org/)>`__ (an +or ask on `RocketChat `__ (an alternative to Slack). diff --git a/docs/source/starter/fabric-starter-kit.rst b/docs/source/starter/fabric-starter-kit.rst index 244a3ef1d00..165fb1f34a8 100644 --- a/docs/source/starter/fabric-starter-kit.rst +++ b/docs/source/starter/fabric-starter-kit.rst @@ -3,5 +3,4 @@ Fabric Starter Kit **Coming soon for v1.0** -If you are looking for the v0.6 Starter Kit, you can find it -`here `__. +For Fabric v0.6 you can look at the `v0.6 Starter Kit `__. diff --git a/docs/source/status.rst b/docs/source/status.rst index 1634d4450fb..009a98fdb9a 100644 --- a/docs/source/status.rst +++ b/docs/source/status.rst @@ -1,5 +1,5 @@ Status ================= -This project is an *Active* Hyperledger project. For more information on the history of this project see the `Fabric wiki page `__. Information on what *Active* entails can be found in +This project is an *Active* Hyperledger project. For more information on the history of this project see the `Fabric wiki page `__. Information on what *Active* entails can be found in the `Hyperledger Project Lifecycle document `__. diff --git a/examples/dchackfest/samples/e2e/README.rst b/examples/dchackfest/samples/e2e/README.rst index 0737e6d0618..329eff317c1 100644 --- a/examples/dchackfest/samples/e2e/README.rst +++ b/examples/dchackfest/samples/e2e/README.rst @@ -146,8 +146,7 @@ Using the configtxgen tool We will now use our second tool - configtxgen - to create our ordering service genesis block and a channel configuration artifact. As the abbreviation suggests, -this tool is a configuration transaction generator. More info on the configtxgen -tool can be found `here `__ +this tool is a configuration transaction generator. More info can be can be found in the :doc:`configtxgen tool documentation `. However, at this stage (and for the sake of brevity) we will simply make use of the tool to generate our two artifacts.