Docs: Change docs to be user focussed

Our docs were oriented to developers, this patch changes this to make them user centric and focused on using the operator.
embercsi · Aug 13, 2020 · f6a3693 · f6a3693
1 parent 499041c
commit f6a3693
Show file tree

Hide file tree

Showing 39 changed files with 804 additions and 66 deletions.
diff --git a/docs/_static/css/custom.css b/docs/_static/css/custom.css
@@ -0,0 +1,6 @@
+img.boxed-img {
+    border: 1px solid #ddd;
+    border-radius: 4px;
+    padding: 5px;
+    margin-bottom: 20px;
+}
diff --git a/docs/authors.rst b/docs/authors.rst
diff --git a/docs/conf.py b/docs/conf.py
@@ -15,8 +15,8 @@
 
 import sys
 import os
-import recommonmark
-from recommonmark import transform as md_transform
+# import recommonmark
+# from recommonmark import transform as md_transform
 
 # If extensions (or modules to document with autodoc) are in another
 # directory, add these directories to sys.path here. If the directory is
@@ -37,7 +37,8 @@
 
 for module in ('cinderlib', 'google', 'google.protobuf', 'eventlet',
                'kubernetes', 'grpc', 'concurrent', 'os_brick',
-               'os_brick.initiator', 'oslo_concurrency'):
+               'os_brick.initiator', 'oslo_concurrency', 'oslo_log',
+               'oslo_context'):
     modulefaker.fake_module(module)
 
 
@@ -55,10 +56,6 @@
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
-source_parsers = {
-   '.md': 'recommonmark.parser.CommonMarkParser',
-}
-
 # The suffix of source filenames.
 source_suffix = ['.rst', '.md']
 
@@ -69,8 +66,8 @@
 master_doc = 'index'
 
 # General information about the project.
-project = u'Ember CSI plugin'
-copyright = u"2018, Gorka Eguileor"
+project = u'Ember CSI'
+copyright = u"2018, Red Hat"
 
 # The version info for the project you're documenting, acts as replacement
 # for |version| and |release|, also used in various other places throughout
@@ -145,19 +142,24 @@
 
 # The name of an image file (relative to this directory) to place at the
 # top of the sidebar.
-#html_logo = None
+html_logo = "img/logo.svg"
 
 # The name of an image file (within the static path) to use as favicon
 # of the docs.  This file should be a Windows icon file (.ico) being
 # 16x16 or 32x32 pixels large.
-#html_favicon = None
+html_favicon = "img/favicon.png"
 
 # Add any paths that contain custom static files (such as style sheets)
 # here, relative to this directory. They are copied after the builtin
 # static files, so a file named "default.css" will overwrite the builtin
 # "default.css".
 html_static_path = ['_static']
 
+html_css_files = [
+    'css/custom.css',
+    'custom.css',
+]
+
 # If not '', a 'Last updated on:' timestamp is inserted at every page
 # bottom, using the given strftime format.
 #html_last_updated_fmt = '%b %d, %Y'
@@ -288,11 +290,21 @@
 # If true, do not generate a @detailmenu in the "Top" node's menu.
 #texinfo_no_detailmenu = False
 
-github_doc_root = 'https://github.com/akrog/ember-csi/tree/master/docs/'
+rst_prolog = """
+.. |br| raw:: html
+
+  <br/>
+"""
+
+github_doc_root = 'https://github.com/embercsi/ember-csi/tree/master/docs/'
 
 def setup(app):
-    app.add_config_value('recommonmark_config', {
-            'url_resolver': lambda url: github_doc_root + url,
-            'auto_toc_tree_section': 'Contents',
-            }, True)
-    app.add_transform(md_transform.AutoStructify)
+    for filename in html_css_files:
+        app.add_stylesheet(filename)
+
+# def setup(app):
+#     app.add_config_value('recommonmark_config', {
+#             'url_resolver': lambda url: github_doc_root + url,
+#             'auto_toc_tree_section': 'Contents',
+#             }, True)
+#     app.add_transform(md_transform.AutoStructify)
diff --git a/docs/contributing.rst b/docs/contributing.rst
diff --git a/docs/ember.rst b/docs/ember.rst
@@ -0,0 +1,111 @@
+Introduction
+============
+
+The Container Storage Interface (`CSI`_) is a standard for provision and use block and file storage systems in containerized workloads on Container Orchestration Systems (COs) like OpenShift.
+
+Using this interface new storage systems can be exposed to COs without needing to change the COs code.
+
+Ember-CSI is an Open Source implementation of the `CSI`_ specification supporting storage solutions from multiple vendors by leveraging a library called `cinderlib <https://docs.openstack.org/cinderlib/latest/>`_ that provides an abstraction layer over the storage drivers.
+
+
+Features
+--------
+
+Ember-CSI supports `CSI`_ versions 0.2, 0.3, 1.0, and 1.1 providing the following features:
+
+- Volume provisioning: file and block types
+- Volume cloning
+- Volume deletion
+- Snapshot creation
+- Create volume from a snapshot
+- Snapshots deletion
+- Listing volumes with pagination
+- Listing snapshots with pagination
+- Attaching/Detaching volumes
+- Multi pod attaching (block mode only)
+- Storage capacity reporting
+- Node probing
+
+Limitations
+-----------
+
+There are 2 types of volumes in OpenShift and Kubernetes, Block and File, and while both are supported by Ember-CSI, behind the scenes all the storage drivers in Ember-CSI are for block storage systems.
+
+To provide File volumes from block storage Ember-CSI connects the volumes to the host, formats and present them to the Orchestrator for the containerized workloads.
+
+Since File type volumes are locally attached block volumes they cannot be shared between containers, so the Shared Access (RWX) Access Mode is not supported.
+
+This limitation does not apply to block volumes, that can be mounted in multiple hosts simultaneously and it's the application the one responsible to orchestrate the proper access to the disk.
+
+Supported drivers
+-----------------
+
+Ember-CSI includes a good number of storage drivers, but due to limitation on hardware availability only a small number of them have been validated at one point or another.  In alphabetical order they are:
+
+- HPE3PARFC
+- HPE3PARISCSI
+- KaminarioISCSI
+- LVMVolume
+- PowerMaxFC
+- PowerMaxISCSI
+- QnapISCSI
+- RBD
+- SolidFire
+- SynoISCSI
+- XtremIOFC
+- XtremIOISCSI
+
+The remaining drivers included in Ember-CSI have not been validated yet:
+
+- ACCESSIscsi
+- AS13000
+- FJDXFC
+- FJDXISCSI
+- FlashSystemFC
+- FlashSystemISCSI
+- GPFS
+- GPFSRemote
+- HPELeftHandISCSI
+- HPMSAFC
+- HPMSAISCSI
+- HedvigISCSI
+- HuaweiFC
+- HuaweiISCSI
+- IBMStorage
+- InStorageMCSFC
+- InStorageMCSISCSI
+- InfortrendCLIFC
+- InfortrendCLIISCSI
+- LenovoFC
+- LenovoISCSI
+- LinstorDrbd
+- LinstorIscsi
+- MStorageFC
+- MStorageISCSI
+- MacroSANFC
+- MacroSANISCSI
+- NetAppCmodeFibreChannel
+- NetAppCmodeISCSI
+- NexentaISCSI
+- PSSeriesISCSI
+- PureFC
+- PureISCSI
+- Quobyte
+- RSD
+- SCFC
+- SCISCSI
+- SPDK
+- Sheepdog
+- StorPool
+- StorwizeSVCFC
+- StorwizeSVCISCSI
+- Unity
+- VNX
+- VZStorage
+- VxFlexOS
+- WindowsISCSI
+- WindowsSmbfs
+- ZadaraVPSAISCS
+
+
+.. _CSI: https://github.com/container-storage-interface/spec
diff --git a/docs/history.md b/docs/history.md
diff --git a/docs/img/advanced-settings.png b/docs/img/advanced-settings.png
diff --git a/docs/img/favicon.png b/docs/img/favicon.png
diff --git a/docs/img/install/01-operatorhub.png b/docs/img/install/01-operatorhub.png
diff --git a/docs/img/install/02-operatorhub-search-ember.png b/docs/img/install/02-operatorhub-search-ember.png
diff --git a/docs/img/install/03-confirm-community.png b/docs/img/install/03-confirm-community.png
diff --git a/docs/img/install/04-install-1.png b/docs/img/install/04-install-1.png
diff --git a/docs/img/install/05-install-2.png b/docs/img/install/05-install-2.png
diff --git a/docs/img/install/06-installing.png b/docs/img/install/06-installing.png
diff --git a/docs/img/install/07-succeeded.png b/docs/img/install/07-succeeded.png
diff --git a/docs/img/install/08-create-storage-banckend.png b/docs/img/install/08-create-storage-banckend.png
diff --git a/docs/img/install/09-name-and-driver.png b/docs/img/install/09-name-and-driver.png
diff --git a/docs/img/install/10-create-backend.png b/docs/img/install/10-create-backend.png
diff --git a/docs/img/install/11-EmberStorageBackends.png b/docs/img/install/11-EmberStorageBackends.png
diff --git a/docs/img/install/12-StatefulSet.png b/docs/img/install/12-StatefulSet.png
diff --git a/docs/img/install/13-DaemonSet.png b/docs/img/install/13-DaemonSet.png
diff --git a/docs/img/install/14-ReplicaSets.png b/docs/img/install/14-ReplicaSets.png
diff --git a/docs/img/install/15-StorageClass.png b/docs/img/install/15-StorageClass.png
diff --git a/docs/img/install/16-edit-annotations.png b/docs/img/install/16-edit-annotations.png
diff --git a/docs/img/install/17-default-sc.png b/docs/img/install/17-default-sc.png
diff --git a/docs/img/logo.svg b/docs/img/logo.svg
diff --git a/docs/img/troubleshoot/01-debug-logs.png b/docs/img/troubleshoot/01-debug-logs.png
diff --git a/docs/img/usage/01-PVCs.png b/docs/img/usage/01-PVCs.png
diff --git a/docs/img/usage/02-create-pvc.png b/docs/img/usage/02-create-pvc.png
diff --git a/docs/img/usage/03-expand-action.png b/docs/img/usage/03-expand-action.png
diff --git a/docs/img/usage/04-expand-size.png b/docs/img/usage/04-expand-size.png
diff --git a/docs/img/usage/05-delete-volume.png b/docs/img/usage/05-delete-volume.png
diff --git a/docs/img/usage/06-delete-confirmation.png b/docs/img/usage/06-delete-confirmation.png
diff --git a/docs/index.rst b/docs/index.rst
@@ -1,21 +1,16 @@
-Welcome to Ember CSI plugin's documentation!
-============================================
+Ember CSI
+=========
 
-Contents:
+Welcome to the Ember-CSI documentation!
+
+Ember-CSI is a plugin to provision and use block and file storage in containerized workloads on Kubernetes and OpenShift.
+
+The documentation for the site is organized into the following sections:
 
 .. toctree::
    :maxdepth: 2
 
-   readme
+   ember
    installation
    usage
-   contributing
-   authors
-   history
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+   troubleshooting