Merge pull request #11412 from lucperkins/lperkins/docs-restructuring-v2

Restructure documentation source files
etcd-io · Jan 27, 2020 · 3898452 · 3898452
2 parents 342c246 + 2f25061
commit 3898452
Show file tree

Hide file tree

Showing 67 changed files with 105 additions and 6,656 deletions.
diff --git a/Documentation/README.md b/Documentation/README.md
diff --git a/Documentation/README.md b/Documentation/README.md
@@ -0,0 +1,5 @@
+# The etcd documentation
+
+etcd is a distributed key-value store designed to reliably and quickly preserve and provide access to critical data. It enables reliable distributed coordination through distributed locking, leader elections, and write barriers. An etcd cluster is intended for high availability and permanent data storage and retrieval.
+
+Please note that the files in this directory are *source files* for the built and rendered documentation that can be viewed at [etcd.io/docs](https://etcd.io/docs).
diff --git a/Documentation/_index.md b/Documentation/_index.md
@@ -0,0 +1,5 @@
+---
+title: etcd version ___
+---
+
+These docs cover everything from setting up and running an etcd cluster to using etcd in applications. Improvements to these docs are encouraged through [pull requests](https://help.github.com/en/articles/about-pull-requests) to the [etcd project](https://github.com/etcd-io/etcd) on GitHub.
diff --git a/Documentation/benchmarks/_index.md b/Documentation/benchmarks/_index.md
@@ -0,0 +1,3 @@
+---
+title: Benchmarks
+---
diff --git a/Documentation/branch_management.md → Documentation/branch-management.md b/Documentation/branch_management.md → Documentation/branch-management.md
@@ -1,5 +1,6 @@
 ---
 title: Branch management
+weight: 1
 ---
 
 ## Guide

diff --git a/Documentation/demo.md b/Documentation/demo.md
@@ -1,16 +1,17 @@
 ---
 title: Demo
+weight: 1
 ---
 
 This series of examples shows the basic procedures for working with an etcd cluster.
 
 ## Set up a cluster
 
-<img src="https://storage.googleapis.com/etcd/demo/01_etcd_clustering_2016051001.gif" alt="01_etcd_clustering_2016050601"/>
+![01_etcd_clustering_2016050601](https://storage.googleapis.com/etcd/demo/01_etcd_clustering_2016051001.gif)
 
 On each etcd node, specify the cluster members:
 
-```
+```shell
 TOKEN=token-01
 CLUSTER_STATE=new
 NAME_1=machine-1
@@ -24,7 +25,7 @@ CLUSTER=${NAME_1}=http://${HOST_1}:2380,${NAME_2}=http://${HOST_2}:2380,${NAME_3
 
 Run this on each machine:
 
-```
+```shell
 # For machine 1
 THIS_NAME=${NAME_1}
 THIS_IP=${HOST_1}
@@ -55,7 +56,7 @@ etcd --data-dir=data.etcd --name ${THIS_NAME} \
 
 Or use our public discovery service:
 
-```
+```shell
 curl https://discovery.etcd.io/new?size=3
 https://discovery.etcd.io/a81b5818e67a6ea83e9d4daea5ecbc92
 
@@ -97,7 +98,7 @@ etcd --data-dir=data.etcd --name ${THIS_NAME} \
 
 Now etcd is ready! To connect to etcd with etcdctl:
 
-```
+```shell
 export ETCDCTL_API=3
 HOST_1=10.240.0.17
 HOST_2=10.240.0.18
@@ -110,27 +111,27 @@ etcdctl --endpoints=$ENDPOINTS member list
 
 ## Access etcd
 
-<img src="https://storage.googleapis.com/etcd/demo/02_etcdctl_access_etcd_2016051001.gif" alt="02_etcdctl_access_etcd_2016051001"/>
+![02_etcdctl_access_etcd_2016051001](https://storage.googleapis.com/etcd/demo/02_etcdctl_access_etcd_2016051001.gif)
 
 `put` command to write:
 
-```
+```shell
 etcdctl --endpoints=$ENDPOINTS put foo "Hello World!"
 ```
 
 `get` to read from etcd:
 
-```
+```shell
 etcdctl --endpoints=$ENDPOINTS get foo
 etcdctl --endpoints=$ENDPOINTS --write-out="json" get foo
 ```
 
 
 ## Get by prefix
 
-<img src="https://storage.googleapis.com/etcd/demo/03_etcdctl_get_by_prefix_2016050501.gif" alt="03_etcdctl_get_by_prefix_2016050501"/>
+![03_etcdctl_get_by_prefix_2016050501](https://storage.googleapis.com/etcd/demo/03_etcdctl_get_by_prefix_2016050501.gif)
 
-```
+```shell
 etcdctl --endpoints=$ENDPOINTS put web1 value1
 etcdctl --endpoints=$ENDPOINTS put web2 value2
 etcdctl --endpoints=$ENDPOINTS put web3 value3
@@ -141,9 +142,9 @@ etcdctl --endpoints=$ENDPOINTS get web --prefix
 
 ## Delete
 
-<img src="https://storage.googleapis.com/etcd/demo/04_etcdctl_delete_2016050601.gif" alt="04_etcdctl_delete_2016050601"/>
+![04_etcdctl_delete_2016050601](https://storage.googleapis.com/etcd/demo/04_etcdctl_delete_2016050601.gif)
 
-```
+```shell
 etcdctl --endpoints=$ENDPOINTS put key myvalue
 etcdctl --endpoints=$ENDPOINTS del key
 
@@ -157,9 +158,9 @@ etcdctl --endpoints=$ENDPOINTS del k --prefix
 
 `txn` to wrap multiple requests into one transaction:
 
-<img src="https://storage.googleapis.com/etcd/demo/05_etcdctl_transaction_2016050501.gif" alt="05_etcdctl_transaction_2016050501"/>
+![05_etcdctl_transaction_2016050501](https://storage.googleapis.com/etcd/demo/05_etcdctl_transaction_2016050501.gif)
 
-```
+```shell
 etcdctl --endpoints=$ENDPOINTS put user1 bad
 etcdctl --endpoints=$ENDPOINTS txn --interactive
 
@@ -178,9 +179,9 @@ put user1 good
 
 `watch` to get notified of future changes:
 
-<img src="https://storage.googleapis.com/etcd/demo/06_etcdctl_watch_2016050501.gif" alt="06_etcdctl_watch_2016050501"/>
+![06_etcdctl_watch_2016050501](https://storage.googleapis.com/etcd/demo/06_etcdctl_watch_2016050501.gif)
 
-```
+```shell
 etcdctl --endpoints=$ENDPOINTS watch stock1
 etcdctl --endpoints=$ENDPOINTS put stock1 1000
 
@@ -194,9 +195,10 @@ etcdctl --endpoints=$ENDPOINTS put stock2 20
 
 `lease` to write with TTL:
 
-<img src="https://storage.googleapis.com/etcd/demo/07_etcdctl_lease_2016050501.gif" alt="07_etcdctl_lease_2016050501"/>
 
-```
+![07_etcdctl_lease_2016050501](https://storage.googleapis.com/etcd/demo/07_etcdctl_lease_2016050501.gif)
+
+```shell
 etcdctl --endpoints=$ENDPOINTS lease grant 300
 # lease 2be7547fbc6a5afa granted with TTL(300s)
 
@@ -214,9 +216,9 @@ etcdctl --endpoints=$ENDPOINTS get sample
 
 `lock` for distributed lock:
 
-<img src="https://storage.googleapis.com/etcd/demo/08_etcdctl_lock_2016050501.gif" alt="08_etcdctl_lock_2016050501"/>
+![08_etcdctl_lock_2016050501](https://storage.googleapis.com/etcd/demo/08_etcdctl_lock_2016050501.gif)
 
-```
+```shell
 etcdctl --endpoints=$ENDPOINTS lock mutex1
 
 # another client with the same name blocks
@@ -228,9 +230,9 @@ etcdctl --endpoints=$ENDPOINTS lock mutex1
 
 `elect` for leader election:
 
-<img src="https://storage.googleapis.com/etcd/demo/09_etcdctl_elect_2016050501.gif" alt="09_etcdctl_elect_2016050501"/>
+![09_etcdctl_elect_2016050501](https://storage.googleapis.com/etcd/demo/09_etcdctl_elect_2016050501.gif)
 
-```
+```shell
 etcdctl --endpoints=$ENDPOINTS elect one p1
 
 # another client with the same name blocks
@@ -242,9 +244,9 @@ etcdctl --endpoints=$ENDPOINTS elect one p2
 
 Specify the initial cluster configuration for each machine:
 
-<img src="https://storage.googleapis.com/etcd/demo/10_etcdctl_endpoint_2016050501.gif" alt="10_etcdctl_endpoint_2016050501"/>
+![10_etcdctl_endpoint_2016050501](https://storage.googleapis.com/etcd/demo/10_etcdctl_endpoint_2016050501.gif)
 
-```
+```shell
 etcdctl --write-out=table --endpoints=$ENDPOINTS endpoint status
 
 +------------------+------------------+---------+---------+-----------+-----------+------------+
@@ -256,7 +258,7 @@ etcdctl --write-out=table --endpoints=$ENDPOINTS endpoint status
 +------------------+------------------+---------+---------+-----------+-----------+------------+
 ```
 
-```
+```shell
 etcdctl --endpoints=$ENDPOINTS endpoint health
 
 10.240.0.17:2379 is healthy: successfully committed proposal: took = 3.345431ms
@@ -269,18 +271,18 @@ etcdctl --endpoints=$ENDPOINTS endpoint health
 
 `snapshot` to save point-in-time snapshot of etcd database:
 
-<img src="https://storage.googleapis.com/etcd/demo/11_etcdctl_snapshot_2016051001.gif" alt="11_etcdctl_snapshot_2016051001"/>
+![11_etcdctl_snapshot_2016051001](https://storage.googleapis.com/etcd/demo/11_etcdctl_snapshot_2016051001.gif)
 
 Snapshot can only be requested from one etcd node, so `--endpoints` flag should contain only one endpoint.
 
-```
+```shell
 ENDPOINTS=$HOST_1:2379
 etcdctl --endpoints=$ENDPOINTS snapshot save my.db
 
 Snapshot saved at my.db
 ```
 
-```
+```shell
 etcdctl --write-out=table --endpoints=$ENDPOINTS snapshot status my.db
 
 +---------+----------+------------+------------+
@@ -295,9 +297,10 @@ etcdctl --write-out=table --endpoints=$ENDPOINTS snapshot status my.db
 
 `migrate` to transform etcd v2 to v3 data:
 
-<img src="https://storage.googleapis.com/etcd/demo/12_etcdctl_migrate_2016061602.gif" alt="12_etcdctl_migrate_2016061602"/>
+![12_etcdctl_migrate_2016061602](https://storage.googleapis.com/etcd/demo/12_etcdctl_migrate_2016061602.gif)
 
-```
+
+```shell
 # write key in etcd version 2 store
 export ETCDCTL_API=2
 etcdctl --endpoints=http://$ENDPOINT set foo bar
@@ -322,9 +325,9 @@ etcdctl --endpoints=$ENDPOINTS get /foo
 
 `member` to add,remove,update membership:
 
-<img src="https://storage.googleapis.com/etcd/demo/13_etcdctl_member_2016062301.gif" alt="13_etcdctl_member_2016062301"/>
+![13_etcdctl_member_2016062301](https://storage.googleapis.com/etcd/demo/13_etcdctl_member_2016062301.gif)
 
-```
+```shell
 # For each machine
 TOKEN=my-etcd-token-1
 CLUSTER_STATE=new
@@ -375,7 +378,7 @@ etcd --data-dir=data.etcd --name ${THIS_NAME} \
 
 Then replace a member with `member remove` and `member add` commands:
 
-```
+```shell
 # get member ID
 export ETCDCTL_API=3
 HOST_1=10.240.0.13
@@ -403,7 +406,7 @@ etcdctl --endpoints=${HOST_1}:2379,${HOST_2}:2379 \
 
 Next, start the new member with `--initial-cluster-state existing` flag:
 
-```
+```shell
 # [WARNING] If the new member starts from the same disk space,
 # make sure to remove the data directory of the old member
 #
@@ -435,9 +438,9 @@ etcd --data-dir=data.etcd --name ${THIS_NAME} \
 
 `auth`,`user`,`role` for authentication:
 
-<img src="https://storage.googleapis.com/etcd/demo/14_etcdctl_auth_2016062301.gif" alt="14_etcdctl_auth_2016062301"/>
+![14_etcdctl_auth_2016062301](https://storage.googleapis.com/etcd/demo/14_etcdctl_auth_2016062301.gif)
 
-```
+```shell
 export ETCDCTL_API=3
 ENDPOINTS=localhost:2379
 

diff --git a/Documentation/dev-guide/_index.md b/Documentation/dev-guide/_index.md
@@ -0,0 +1,3 @@
+---
+title: Developer guide
+---
diff --git a/Documentation/dev-internal/discovery_protocol.md b/Documentation/dev-internal/discovery_protocol.md
@@ -109,7 +109,7 @@ The status for this discovery token, including the machines that have been regis
 
 The repository is located at https://github.com/coreos/discovery.etcd.io. It could be used to build a custom discovery service.
 
-[api]: ../v2/api.md#waiting-for-a-change
-[cluster-size]: ../v2/admin_guide.md#optimal-cluster-size
+[api]: /docs/v2/api#waiting-for-a-change
+[cluster-size]: /docs/v2/admin_guide#optimal-cluster-size
 [expected-cluster-size]: #specifying-the-expected-cluster-size
 [new-discovery-token]: #creating-a-new-discovery-token
diff --git a/Documentation/dl_build.md → Documentation/dl-build.md b/Documentation/dl_build.md → Documentation/dl-build.md