[FAB-3488] Add documentation on how the doc gets built

Fix [FAB-3488] by adding a new README file in the docs directory
providing information gathered from Nick Gaski and Ramesh Thoomu
on how the documentation is built and gets published as well as
information one needs to know to be able to make changes to the
doc.

Implemented Nick's suggested improvements.

Implemented Tracy's suggested improvements.

[ci-skip]

Change-Id: I93538d66e14815dff731153fdd46020e5f2ac57c
Signed-off-by: Arnaud J Le Hors <[email protected]>

Author: lehors

docs/README.md

@@ -0,0 +1,88 @@
+# Documentation README
+
+## Introduction
+
+This document contains information on how the Fabric documentation is
+built and published as well as a few conventions one should be aware of
+before making changes to the doc.
+
+The crux of the documentation is written in
+[reStructuredText](http://docutils.sourceforge.net/rst.html) which is
+converted to HTML using [Sphinx](http://www.sphinx-doc.org/en/stable/).
+The HTML is then published on http://hyperledger-fabric.readthedocs.io
+which has a hook so that any new content that goes into `docs/source`
+on the main repository will trigger a new build and publication of the
+doc.
+
+## Conventions
+
+* Source files are in RST format and found in the `docs/source` directory.
+* The main entry point is index.rst, so to add something into the Table
+  of Contents you would simply modify that file in the same manner as
+  all of the other topics. It's very self-explanatory once you look at
+  it.
+* Relative links should be used whenever possible. The preferred
+  syntax for this is: :doc:\`anchor text <relativepath>\`
+  <br/>Do not put the .rst suffix at the end of the filepath.
+* For non RST files, such as text files, MD or YAML files, link to the
+  file on github, like this one for instance:
+  https://github.com/hyperledger/fabric/blob/master/docs/README.md
+
+Notes: The above means we have a dependency on the github mirror
+repository. Relative links are unfortunately not working on github
+when browsing through a RST file.
+
+## Setup
+
+Making any changes to the documentation will require you to test your
+changes by building the doc in a way similar to how it is done for
+production. There are two possible setups you can use to do so:
+setting up your own staging repo and publication website, or building
+the docs on your machine. The following sections cover both options:
+
+### Setting up your own staging repo and publication website
+
+You can easily build your own staging repo following these steps:
+
+1. Fork [fabric on github](https://github.com/hyperledger/fabric)
+1. From your fork, go to `settings` in the upper right portion of the screen,
+1. click `Integration & services`,
+1. click `Add service` dropdown,
+1. and scroll down to ReadTheDocs.
+1. Next, go to http://readthedocs.org and sign up for an account. One of the first prompts will offer to link to github. Elect this then,
+1. click import a project,
+1. navigate through the options to your fork (e.g. yourgithubid/fabric),
+1. it will ask for a name for this project. Choose something
+intuitive. Your name 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:
+`yourgithubid-fabric.readthedocs.io/en/latest`
+
+Now anytime you modify or add documentation content to your fork, this
+URL will automatically get updated with your changes!
+
+### Building the docs on your machine
+
+Here are the quick steps to achieve this on a local machine without
+depending on ReadTheDocs, starting from the main fabric
+directory. Note: you may need to adjust depending on your OS.
+
+```
+sudo pip install Sphinx
+sudo pip install sphinx_rtd_theme
+cd fabric/docs # Be in this directory. Makefile sits there.
+make html
+```
+
+This will generate all the html files in `docs/build/html` which you can
+then start browsing locally using your browser. Every time you make a
+change to the documentation you will of course need to rerun `make
+html`.
+
+In addition, if you'd like, you may also run a local web server with the following commands (or equivalent depending on your OS):
+
+```
+sudo apt-get install apache2
+cd source/build/html
+sudo cp -r * /var/www/html/
+```
+
+You can then access the html files at `http://localhost/index.html`.