refactor documentation

[christo4ferris]

Description

refactor of docs to make the use of fabric components more accessible to mere mortals and without requiring that binaries and images be built by the user. This turned into a major refactoring exercise.

Motivation and Context

There were a number of things that needed to be addressed. First, there was lots of redundant documentation about how to start components etc that was either conflicting, or at the very least inconsistent. I attempted to refactor things so that there is setup, build, and operational separation.

More could be and should be done, but I don't think it makes sense to leave this outstanding any longer.

Fixes #2144

How Has This Been Tested?

I have gone through and tested the various directions personally.

Checklist:

• I have added a Signed-off-by.
• I have either added documentation to cover my changes or this change requires no new documentation.
• I have either added unit tests to cover my changes or this change requires no new tests.
• [] I have run golint and have fixed valid warnings in code I have added or modified. This tool generates false positives so you may choose to ignore some warnings. The goal is clean, consistent, and readable code.

Signed-off-by: Christopher Ferris chrisfer@us.ibm.com

[dco-bot]

Hi christo4ferris,

Thanks for submitting this pull request!

I can confirm that the DCO1.1 sign-off has been included. It is okay to process this pull request.

dco-bot

[christo4ferris]

I'm interested in initial feedback on my refactor of devnet-setup.md @joshhus @srderson @muralisrini

I am also interested in help with membership services usage. What was previously described is far from comprehensive or informative. It probably deserves a document of its own. I don't feel confident that I know enough (yet) about use of membersrvc to be writing the tutorial, but am willing to give it a go with some guidance.

[srderson]

Link is 404 for me. https://hub.docker.com/u/hyperledger works. Maybe because I'm not logged in?

[srderson]

Looks better already. I'd suggest changing the name of the file from devnet-setup.md to Setting Up a Network.md as it will be more clear in the table of contents at http://hyperledger-fabric.readthedocs.io/en/latest/. Also, I would suggest moving out the the dev-setup folder to possibly just a Setup folder?

[christo4ferris]

@srderson took your suggestion and it is becoming a bit more involved than I had planned originally. However, I am pretty pleased thus far with the progress. I have moved all of the setup to a Setup directory and I added that to the main index. Then I had to accommodate all the moving around which triggered a bit more refactoring.

@rameshthoomu is there a way to generate the mkdocs against a pull request or a personal repo? I'd like to see how this looks.

[rameshthoomu]

@christo4ferris : mkdocs works only on Push notifications. yes, it is possible to setup on a personal repo.
I have pulled this PR and did some modifications to mkdocs.yaml and included index.md in docs folder (It is required for mkdocs to build the documentation). Below is the mkdocs generated document looks like on this PR.

http://chaincode-docs.readthedocs.io/en/latest/. I have observed 404 not found errors in couple places. Will send you the list of observations in sometime.

Just for reference, I have created draft version on ReadTheDocs Readme.md. https://github.com/rameshthoomu/fabric/blob/tools/docs/RTD.md

[christo4ferris]

@rameshthoomu can you please investigate the jenkins "failure" - I used [ci skip] because just docs changed but Jenkins seems to think that skipping == fail. https://jenkins.hyperledger.org/job/fabric-github-verify-x86_64/557/console

[rameshthoomu]

seems there is an open issue in Jenkins ci-skip plugin.. Created an issue in Jenkins JIRA.

[christo4ferris]

@hyperledger/fabric-maintainers @joshhus @nickgaski @mastersingh24 @smithbk I think that this is ready to merge. The docs still need some additional attention, but this hopefully makes things a bit better organized and hopefully up to date (worked on my machine;-)

[christo4ferris]

check that... just had a discussion with @muralisrini about --peer-chaincodedev flag and I need to tweak the chaincode dev page a bit before we merge.

[christo4ferris]

okay @hyperledger/fabric-maintainers @joshhus @nickgaski @mastersingh24 @smithbk I think that this is ready for review. Thanks.

[christo4ferris]

Note that Jenkins failure is result of Jenkins bug with [ci skip]. There are no code changes in this PR (well, excepting to a comment in core.yaml that changed the reference to a markdown file).

[joshhus]

" 'peer' and deployed chaincode." ?

[christo4ferris]

thanks @srderson @JonathanLevi @joshhus for the reviews!

[srderson]

LGTM. Thanks for the reviews @JonathanLevi and @joshhus ! We can continue making improvements in future PRs.

[joshhus]

I'm adding comments to the PR, much better method.

[joshhus]

ah okay, next one.

[joshhus]

"... of its required state attributes ..." ? or "states" ...
"... and write its state ..." or "states"

[christo4ferris]

@joshhus sorry, thought you were done... @JonathanLevi plans to take on ca-setup.md. Please feel free to submit PRs for any other changes.

[joshhus]

I looked at some of the other files incl. /devenv.md and /build.md, and find nothing major - looks good. Minor nits to look out for moving fwd (can reduce translation flags down the road):

• Vagrant and Docker and Behave always capitalized, unless as dir names, e.g.
• When introducing a following code sample or list, e.g., end the lead-in sentence with a colon: (rather than nothing, or a period.)
• Use "set up" two words when it's a verb; use "setup" one word when it's a noun.