build docs

Change-Id: Ida67463533ae9ddf5508c290e9fe898605bd4659

.gitignore

@@ -22,3 +22,6 @@ bin
 *.swp
 *.swo
 *~
+
+doc/build
+.tox

.zuul.yaml

@@ -49,6 +49,8 @@
       minikube_dns_resolvers: ['1.1.1.1', '8.8.8.8']
 
 - project:
+    templates:
+      - publish-opendev-tox-docs
     check:
       jobs:
         - golangci-lint

doc/requirements.txt

@@ -0,0 +1,2 @@
+doc8
+sphinx

doc/source/conf.py

@@ -0,0 +1,3 @@
+project = 'OpenStack Operator'
+copyright = '2020, VEXXHOST, Inc.'
+author = 'VEXXHOST, Inc.'

doc/source/custom-resources.rst

@@ -0,0 +1,8 @@
+Custom Resources
+================
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   custom-resources/*

doc/source/custom-resources/mcrouter.rst

@@ -0,0 +1,23 @@
+.. _mcrouter:
+
+Mcrouter
+########
+
+Mcrouter is a memcached protocol router for scaling Memcached deployments. It
+is a core component of cache infrastructure at Facebook and Instagram where
+Mcrouter handles almost 5 billion requests per second at peak.
+
+Architecture
+************
+
+This resource creates a ``Deployment`` with a hard coded replica count of two
+which hosts two identical instances of ``mcrouter`` for redundancy purposes.
+
+It also exposes a ``Service`` resource which points at the two ``mcrouter``
+instances running.
+
+Usage
+*****
+
+.. literalinclude :: ../../../config/samples/infrastructure_v1alpha1_mcrouter.yaml
+   :language: yaml

doc/source/custom-resources/memcached.rst

@@ -0,0 +1,25 @@
+.. _memcached:
+
+Memcached
+#########
+
+Memcached is an in-memory key-value store for small chunks of arbitrary
+data (strings, objects) from results of database calls, API calls, or page
+rendering.
+
+Architecture
+************
+
+This resource creates a ``Deployment`` with a hard coded replica count of two,
+the size of every replica corresponds to half the size provided inside the
+custom resource.
+
+This resource does not expose a headless service, instead, it creates a managed
+resource of :ref:`Mcrouter` which is automatically updated with the IPs of the
+pods that are running ``memcached``.
+
+Usage
+*****
+
+.. literalinclude :: ../../../config/samples/infrastructure_v1alpha1_memcached.yaml
+   :language: yaml

doc/source/index.rst

@@ -0,0 +1,7 @@
+OpenStack Operator
+==================
+
+.. toctree::
+   :maxdepth: 2
+
+   custom-resources

docs/components/mcrouter.md

@@ -1,35 +0,0 @@
-# Mcrouter
-
-Mcrouter is a memcached protocol router for scaling Memcached deployments. It
-is a core component of cache infrastructure at Facebook and Instagram where
-Mcrouter handles almost 5 billion requests per second at peak.
-
-OpenStack usually comes down to a halt if one of the Memcached instances don't
-respond anymore.  Mcrouter is used to enable high availability and redundancy
-so that any Memcached outages will not affect the OpenStack services.
-
-The only two possible reasons that we can have a full system slowdown at the
-moment remains:
-
-- All backends (Memcached instances) are all down
-- All Mcrouter replicas are down
-
-The first probably means there's a bigger issue in play, the latter will
-likely automatically recover by Kubernetes ensuring that replicas come back
-up.  Also, due to the fact that the service is exposed as a ClusterIP, it only
-takes a single replica to be up for everything to come back to start working
-again.
-
-## Example
-
-```yaml
-apiVersion: infrastructure.vexxhost.cloud/v1alpha1
-kind: Mcrouter
-metadata:
-  name: sample
-spec:
-  route: PoolRoute|default
-  pools:
-    default:
-      servers: ['10.0.0.1:11211', '10.0.0.2:11211']
-```

docs/components/memcached.md

@@ -1,26 +0,0 @@
-# Memcached
-
-Memcached is an in-memory key-value store for small chunks of arbitrary
-data (strings, objects) from results of database calls, API calls, or page
-rendering.
-
-It's used in OpenStack for a lot of token caching and in other services such
-as Nova to minimize load against the database cluster.  This operator allows
-you to deploy it and it automatically exposes a single IP address which will
-point towards any of the two Mcrouter instances which are pushing data out to
-the Memcached instances.
-
-It will also automatically take the total number of megabytes and split it 
-across two shards (so setting `megabytes` to `128`) will result in two instances
-each with 64 megabytes which are load balanced via Mcrouter.
-
-## Example
-
-```yaml
-apiVersion: infrastructure.vexxhost.cloud/v1alpha1
-kind: Memcached
-metadata:
-  name: sample
-spec:
-  megabytes: 128
-```

tox.ini

@@ -0,0 +1,10 @@
+[tox]
+minversion = 2.0
+skipsdist = True
+
+[testenv:docs]
+deps =
+  -r{toxinidir}/doc/requirements.txt
+commands =
+  doc8 doc/source
+  sphinx-build -W -b html -d doc/build/doctrees doc/source doc/build/html