Merge pull request hyperledger#1101 from michaeldboyd/docs-feature

Added readthedocs support for the docs directory

.gitignore

@@ -10,6 +10,7 @@ __pycache__/
 # Distribution / packaging
 bin/
 build/
+_build/
 develop-eggs/
 dist/
 eggs/

README.md

@@ -1,5 +1,5 @@
 ![logo](collateral/logos/indy-logo.png)
-
+# Indy Node
 * [About Indy Node](#about-indy-node)
 * [Technical Overview of Indy Blockchain](#technical-overview-of-indy-blockchain)
 * [Indy Node Repository Structure](#indy-node-repository-structure)
@@ -40,7 +40,7 @@ with a different network, using whatever conventions a community chooses.
 Please visit [Technical Overview of Plenum](https://github.com/hyperledger/indy-plenum/blob/master/docs/main.md).
 
 More documentation can be found in [indy-plenum-docs](https://github.com/hyperledger/indy-plenum/blob/master/docs)
-and [indy-node-docs](docs).
+and [indy-node-docs](docs/source/).
 
 ## Indy Node Repository Structure
 
@@ -90,7 +90,7 @@ Use project name `INDY`.
 
 ## How to Install a Test Network 
 
-You can have a look at [Start Nodes](docs/start-nodes.md) 
+You can have a look at [Start Nodes](docs/source/start-nodes.md) 
 to understand what needs to be done to create a Network, initialize and start Nodes, and what scripts are provided for this.
 
 The described process is automated in one of the ways below (it allow to install a test Network):
@@ -107,16 +107,16 @@ The described process is automated in one of the ways below (it allow to install
 
 ## How to Start Working with the Code
 
-Please have a look at [Dev Setup](docs/setup-dev.md)
+Please have a look at [Dev Setup](docs/source/setup-dev.md)
 
 
 ## Continuous Integration and Delivery
 
-Please have a look at [Continuous integration/delivery](docs/ci-cd.md)
+Please have a look at [Continuous integration/delivery](docs/source/ci-cd.md)
 
 ## How to send a PR
 
-- Make sure that you followed [write code guideline](docs/write-code-guideline.md) before sending a PR
+- Make sure that you followed [write code guideline](docs/source/write-code-guideline.md) before sending a PR
 - Do not create big PRs; send a PR for one feature or bug fix only.
  If a feature is too big, consider splitting a big PR to a number of small ones.
 - Consider sending a design doc into `design` folder (as markdown or PlantUML diagram) for a new feature  before implementing it
@@ -147,21 +147,21 @@ If you made changes in both indy-plenum and indy-node, you need to do the follow
 ## Docs and links
 
 - Indy-plenum is based on [RBFT](https://pakupaku.me/plaublin/rbft/5000a297.pdf) protocol
-- Please have a look at documents and diagrams in [docs](docs) folder
-- Please have a look at documents and diagrams in Plenum's [docs](https://github.com/hyperledger/indy-plenum/tree/master/docs) folder:
-    - [Technical Overview of Plenum](https://github.com/hyperledger/indy-plenum/blob/master/docs/main.md)
-    - [Plenum Consensus Algorithm Diagram](https://github.com/hyperledger/indy-plenum/blob/master/docs/diagrams/consensus-protocol.png)
-    - [Glossary](https://github.com/hyperledger/indy-plenum/blob/master/docs/glossary.md)
-    - [Storages](https://github.com/hyperledger/indy-plenum/blob/master/docs/storage.md)
-    - [Request Handling](https://github.com/hyperledger/indy-plenum/blob/master/docs/request_handling.md)
-    - [Catchup](https://github.com/hyperledger/indy-plenum/blob/master/docs/catchup.md)
-    - [Catchup Diagram](https://github.com/hyperledger/indy-plenum/blob/master/docs/diagrams/catchup-procedure.png)
-    - [Plugins](https://github.com/hyperledger/indy-plenum/blob/master/docs/plugins.md)
-- Relationship between Entities and Transactions: [relationship diagram](docs/relationship-diagram.png)
-- Supported transactions and their format: [transactions](docs/transactions.md)
-- Supported requests (write, read) and their format: [requests](docs/requests.md)
-- [Network roles and permissions](https://github.com/hyperledger/indy-node/blob/master/docs/auth_rules.md)
-- [Indy file folder structure guideline](docs/indy-file-structure-guideline.md)
-- [Helper Scripts](docs/helper-scripts.md)
-- [Pool Upgrade](docs/pool-upgrade.md)
-- [Node Addition](docs/add-node.md)
+- Please have a look at documents and diagrams in [docs/source](docs/source) folder
+- Please have a look at documents and diagrams in Plenum's [docs](https://github.com/hyperledger/indy-plenum/tree/master/docs) folder, or on https://indy.readthedocs.io/projects/plenum :
+    - [Technical Overview of Plenum](https://github.com/hyperledger/indy-plenum/blob/master/docs/source/main.md)
+    - [Plenum Consensus Algorithm Diagram](https://github.com/hyperledger/indy-plenum/blob/master/docs/source/diagrams/consensus-protocol.png)
+    - [Glossary](https://github.com/hyperledger/indy-plenum/blob/master/docs/source/glossary.md)
+    - [Storages](https://github.com/hyperledger/indy-plenum/blob/master/docs/source/storage.md)
+    - [Request Handling](https://github.com/hyperledger/indy-plenum/blob/master/docs/source/request_handling.md)
+    - [Catchup](https://github.com/hyperledger/indy-plenum/blob/master/docs/source/catchup.md)
+    - [Catchup Diagram](https://github.com/hyperledger/indy-plenum/blob/master/docs/source/diagrams/catchup-procedure.png)
+    - [Plugins](https://github.com/hyperledger/indy-plenum/blob/master/docs/source/plugins.md)
+- Relationship between Entities and Transactions: [relationship diagram](docs/source/relationship-diagram.png)
+- Supported transactions and their format: [transactions](docs/source/transactions.md)
+- Supported requests (write, read) and their format: [requests](docs/source/requests.md)
+- [Network roles and permissions](https://github.com/hyperledger/indy-node/blob/master/docs/source/auth_rules.md)
+- [Indy file folder structure guideline](docs/source/indy-file-structure-guideline.md)
+- [Helper Scripts](docs/source/helper-scripts.md)
+- [Pool Upgrade](docs/source/pool-upgrade.md)
+- [Node Addition](docs/source/add-node.md)

docs/README.md

@@ -0,0 +1,55 @@
+# Documentation README
+Check out the docs at http://hyperledger-indy.readthedocs.io/projects/node
+
+Learn more about how our docs are built and maintained at http://hyperledger-indy.readthedocs.io/en/latest/docs.html
+
+This `docs/` directory should contain all of the documents associated with the repository, with the exception of README files that describe technical details with the directories of code. 
+
+The `docs/source/` directory contains all of the documentation that is built and hosted on readthedocs. Based on the maintainer's discretion, some docs may not be necessary to build on readthedocs, and can exist within the `docs/` directory but outside of the `source/` directory. 
+
+
+## How to Add Documentation
+For new features and pull requests, maintainers should make sure that the **contributor has added an explanation for their changes in the docs folder before merging the PR.**
+
+Contributors should add a new file to the docs/source/ folder or write an addition to a current file that explains what their feature is and how it works. If needed, they may also add a link to more technical README's located nearer to the code.
+
+Whenever additions are made to the docs, make sure to update the `index.rst` in whichever folder the file has been added, and build the docs locally to confirm they work (TODO: add the `sphinx-build` command to our CI/CD flow).
+
+For example, if I wanted to add another file to the indy-sdk docs/ folder named `glossary.md`, I would create the file, and then add a reference to it in the `index.rst`: 
+```
+.. toctree::
+  :maxdepth: 1
+  :hidden:
+
+  getting-started/index.rst
+  ...
+  key-concepts.md
+  ...
+  contributing/index.rst
+  ...
+  glossary.md                   .. <-- this is your new file!
+
+```
+
+To add a new file to a subfolder, simply update the subfolder's `index.rst` with the relative link to your file.
+
+If you'd like to link to a file outside of the docs/ folder, you'll need to provide an external github link (this is by design, to keep our docs organized into a single folder)
+
+## Building the docs on your machine
+
+Here are the quick steps to achieve this on a local machine without depending on ReadTheDocs. Note: Instructions may differ depending on your OS.
+Run these commands within the repository folder
+```bash
+cd docs/source # Be in this directory. Makefile sits there.
+pip install -r requirements.txt
+make html
+```
+
+This will generate all the html files in `docs/source/_build/html` which you can then browse locally in your browser. Every time you make a change to the documentation you will need to rerun `make html`.
+
+## Additional Instructions
+This section is to be used for repo maintainers to add additional documentation guidelines or instructions. 
+**TODO: Build the respective code API's into the readthedocs website**
+
+**TODO: Add table support for markdown files** 
+* This link may help: https://github.com/ryanfox/sphinx-markdown-tables

docs/source/Makefile

@@ -0,0 +1,19 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)