From fb9495099dcca9d1fd0e0b487c9e846c9876d070 Mon Sep 17 00:00:00 2001 From: Nikolay Mahotkin Date: Wed, 14 Sep 2016 15:51:19 +0300 Subject: [PATCH] Adding initial doc hierarchy for building with sphinx * Added generic .gitignore file * Added initial sphinx config file * Imported 2 doc pages from repo: - Kubernetes cluster - Docker interfaces library Change-Id: Iff43fa4afe899a548f9992a2bb4b280397098222 --- .gitignore | 47 +++++++++- doc/README.md | 6 ++ doc/source/README.rst | 1 + doc/source/_templates/sidebarlinks.html | 11 +++ doc/source/_theme/layout.html | 4 + doc/source/_theme/theme.conf | 4 + doc/source/cluster.rst | 2 + doc/source/conf.py | 116 ++++++++++++++++++++++++ doc/source/docker_interfaces.rst | 1 + doc/source/index.rst | 21 +++++ 10 files changed, 209 insertions(+), 4 deletions(-) create mode 100644 doc/README.md create mode 100644 doc/source/README.rst create mode 100644 doc/source/_templates/sidebarlinks.html create mode 100644 doc/source/_theme/layout.html create mode 100644 doc/source/_theme/theme.conf create mode 100644 doc/source/cluster.rst create mode 100644 doc/source/conf.py create mode 100644 doc/source/docker_interfaces.rst create mode 100644 doc/source/index.rst diff --git a/.gitignore b/.gitignore index e91ebf4..06b218e 100644 --- a/.gitignore +++ b/.gitignore @@ -1,10 +1,49 @@ -tests/*.py[cod] +*.py[cod] +*.sqlite + +# C extensions +*.so + +# Packages +*.egg +*.egg-info +dist +build +.venv +eggs +parts +bin +var +sdist +develop-eggs +.installed.cfg +lib +lib64 + +# Installer logs +pip-log.txt + +# Unit test / coverage reports +.coverage +.tox +nosetests.xml +cover/* +.testrepository/ +subunit.log +AUTHORS +ChangeLog + +# Translations +*.mo # Mr Developer +.mr.developer.cfg +.project +.pydevproject .idea +.DS_Store +etc/*.conf -# Linux swap file +#Linux swap file *.swp -# Tests results -.tox diff --git a/doc/README.md b/doc/README.md new file mode 100644 index 0000000..85999a5 --- /dev/null +++ b/doc/README.md @@ -0,0 +1,6 @@ +# Sphinx DOC hints + +## Running sphinx: + + sphinx-build -c doc/source doc/build + diff --git a/doc/source/README.rst b/doc/source/README.rst new file mode 100644 index 0000000..a6210d3 --- /dev/null +++ b/doc/source/README.rst @@ -0,0 +1 @@ +.. include:: ../../README.rst diff --git a/doc/source/_templates/sidebarlinks.html b/doc/source/_templates/sidebarlinks.html new file mode 100644 index 0000000..500c0b0 --- /dev/null +++ b/doc/source/_templates/sidebarlinks.html @@ -0,0 +1,11 @@ +

Useful Links

+ + +{% if READTHEDOCS %} + +{% endif %} diff --git a/doc/source/_theme/layout.html b/doc/source/_theme/layout.html new file mode 100644 index 0000000..cd7ade1 --- /dev/null +++ b/doc/source/_theme/layout.html @@ -0,0 +1,4 @@ +{% extends "basic/layout.html" %} +{% set css_files = css_files + ['_static/tweaks.css'] %} + +{% block relbar1 %}{% endblock relbar1 %} \ No newline at end of file diff --git a/doc/source/_theme/theme.conf b/doc/source/_theme/theme.conf new file mode 100644 index 0000000..8c44b0c --- /dev/null +++ b/doc/source/_theme/theme.conf @@ -0,0 +1,4 @@ +[theme] +inherit = nature +stylesheet = nature.css +pygments_style = tango \ No newline at end of file diff --git a/doc/source/cluster.rst b/doc/source/cluster.rst new file mode 100644 index 0000000..3f97ac9 --- /dev/null +++ b/doc/source/cluster.rst @@ -0,0 +1,2 @@ + +.. include:: ../../Kubernetes/README.rst diff --git a/doc/source/conf.py b/doc/source/conf.py new file mode 100644 index 0000000..3c21e6a --- /dev/null +++ b/doc/source/conf.py @@ -0,0 +1,116 @@ +# -*- coding: utf-8 -*- +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or +# implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +import os +import sys + + +on_rtd = os.environ.get('READTHEDOCS', None) == 'True' + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +sys.path.insert(0, os.path.abspath('../../')) +sys.path.insert(0, os.path.abspath('../')) +sys.path.insert(0, os.path.abspath('./')) +# -- General configuration ---------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones. +extensions = [ + 'sphinx.ext.autodoc' +] + +if not on_rtd: + extensions.append('oslosphinx') + +wsme_protocols = ['restjson'] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# autodoc generation is a bit aggressive and a nuisance when doing heavy +# text edit cycles. +# execute "export SPHINX_DEBUG=1" in your terminal to disable + +# The suffix of source filenames. +source_suffix = '.rst' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'Kubernetes & Docker apps' +copyright = u'2016, Murano contributors' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +show_authors = False + +# If true, '()' will be appended to :func: etc. cross-reference text. +add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +add_module_names = True + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# -- Options for HTML output -------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# html_static_path = ['_static'] + +if on_rtd: + html_theme_path = ['.'] + html_theme = 'sphinx_rtd_theme' + +# Output file base name for HTML help builder. +htmlhelp_basename = '%sdoc' % project + +# A list of ignored prefixes for module index sorting. +# modindex_common_prefix = [''] + +# The name for this set of Sphinx documents. If None, it defaults to +# " v documentation". +html_title = 'K8s & Docker' + +# Custom sidebar templates, maps document names to template names. +html_sidebars = { + 'index': [ + 'sidebarlinks.html', 'localtoc.html', 'searchbox.html', 'sourcelink.html' + ], + '**': [ + 'localtoc.html', 'relations.html', + 'searchbox.html', 'sourcelink.html' + ] +} + +# -- Options for manual page output ------------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + ('index', 'docker', u'Kubernetes & Docker', + [u'OpenStack Foundation'], 1) +] + +# If true, show URL addresses after external links. +man_show_urls = True diff --git a/doc/source/docker_interfaces.rst b/doc/source/docker_interfaces.rst new file mode 100644 index 0000000..f4a2215 --- /dev/null +++ b/doc/source/docker_interfaces.rst @@ -0,0 +1 @@ +.. include:: ../../DockerInterfacesLibrary/README.rst diff --git a/doc/source/index.rst b/doc/source/index.rst new file mode 100644 index 0000000..6e6ef6d --- /dev/null +++ b/doc/source/index.rst @@ -0,0 +1,21 @@ +Welcome to Kubernetes & Docker suite documentation! +=================================================== + + +Overview +-------- + + +User guide +---------- + + * :doc:`Kubernetes Cluster guide ` + * :doc:`Docker Interfaces Library guide ` + +Developer guide +--------------- + + +Indices and tables +================== +