From b538ae2215c4c78a917333b6a8b11eca111d868a Mon Sep 17 00:00:00 2001 From: Gorka Eguileor Date: Thu, 2 Aug 2018 17:59:45 +0200 Subject: [PATCH] Sphinx doc build Fix doc building process using Sphinx. --- .gitignore | 2 ++ docs/conf.py | 25 ++++++++++++++++++++++++- docs/history.md | 1 + docs/history.rst | 1 - docs/index.rst | 3 ++- docs/readme.md | 1 + docs/readme.rst | 1 - ember_csi/cl_crd.py | 6 +++--- ember_csi/rpdb.py | 4 +++- requirements_docs.txt | 5 +++++ 10 files changed, 41 insertions(+), 8 deletions(-) create mode 120000 docs/history.md delete mode 100644 docs/history.rst create mode 120000 docs/readme.md delete mode 100644 docs/readme.rst create mode 100644 requirements_docs.txt diff --git a/.gitignore b/.gitignore index aeb58ed5..da62b0d5 100644 --- a/.gitignore +++ b/.gitignore @@ -58,6 +58,8 @@ coverage.xml # Sphinx documentation docs/_build/ +docs/modules.rst +docs/ember_csi.rst # PyBuilder target/ diff --git a/docs/conf.py b/docs/conf.py index a1eb63fe..e5e01adc 100755 --- a/docs/conf.py +++ b/docs/conf.py @@ -15,6 +15,8 @@ import sys import os +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 @@ -31,6 +33,14 @@ # version is used. sys.path.insert(0, project_root) +import modulefaker + +for module in ('cinderlib', 'google', 'google.protobuf', 'eventlet', + 'kubernetes', 'grpc', 'concurrent', 'os_brick', + 'os_brick.initiator', 'oslo_concurrency'): + modulefaker.fake_module(module) + + import ember_csi # -- General configuration --------------------------------------------- @@ -45,8 +55,12 @@ # 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' +source_suffix = ['.rst', '.md'] # The encoding of source files. #source_encoding = 'utf-8-sig' @@ -273,3 +287,12 @@ # 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/' + +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/history.md b/docs/history.md new file mode 120000 index 00000000..a5333ae4 --- /dev/null +++ b/docs/history.md @@ -0,0 +1 @@ +../HISTORY.md \ No newline at end of file diff --git a/docs/history.rst b/docs/history.rst deleted file mode 100644 index 25064996..00000000 --- a/docs/history.rst +++ /dev/null @@ -1 +0,0 @@ -.. include:: ../HISTORY.rst diff --git a/docs/index.rst b/docs/index.rst index 5f2a7308..1b637e4d 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -10,7 +10,8 @@ Contents: installation usage contributing - authorshistory + authors + history Indices and tables ================== diff --git a/docs/readme.md b/docs/readme.md new file mode 120000 index 00000000..32d46ee8 --- /dev/null +++ b/docs/readme.md @@ -0,0 +1 @@ +../README.md \ No newline at end of file diff --git a/docs/readme.rst b/docs/readme.rst deleted file mode 100644 index 72a33558..00000000 --- a/docs/readme.rst +++ /dev/null @@ -1 +0,0 @@ -.. include:: ../README.rst diff --git a/ember_csi/cl_crd.py b/ember_csi/cl_crd.py index 8c83fa07..ae542950 100644 --- a/ember_csi/cl_crd.py +++ b/ember_csi/cl_crd.py @@ -4,7 +4,7 @@ environmental variable is "crd". All Ember-CSI containers (node and controllers) must have the following -RBACs: +RBACs:: # Allow listing and creating CRDs - apiGroups: ['apiextensions.k8s.io'] @@ -17,7 +17,7 @@ verbs: ["*"] Our Custom Resource Objects can be listed with their singular, plural, and -short names: +short names:: kubectl get vol kubectl get volume @@ -36,7 +36,7 @@ kubectl get keyvalues Since they are added to the all and ember categories we can also see them -with: +with:: kubectl get all kubectl get ember diff --git a/ember_csi/rpdb.py b/ember_csi/rpdb.py index 65886de0..67deca59 100644 --- a/ember_csi/rpdb.py +++ b/ember_csi/rpdb.py @@ -16,13 +16,15 @@ Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: + 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. + 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. -THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE diff --git a/requirements_docs.txt b/requirements_docs.txt new file mode 100644 index 00000000..1653f202 --- /dev/null +++ b/requirements_docs.txt @@ -0,0 +1,5 @@ +Sphinx==1.6.5 +recommonmark==0.4.0 +git+https://github.com/akrog/modulefaker.git#egg=modulefaker +git+https://github.com/akrog/cindermock.git +git+https://github.com/akrog/nosbrickmock.git