Browse Source

Berth documentation via build_sphinx.

This PS adds tooling and automation to automatically generate
Berth's documentation into feature-rich HTML pages that can
be hosted.

To run the documentation job, simply execute:

    tox -e docs

Future docs should be written using the style described at
http://www.sphinx-doc.org/en/stable/markup/code.html and
located in berth/docs/source

This PS also adds basic building blocks required by most any
Python project:

  * test-requirements.txt
  * requirements.txt
  * setup.cfg
  * setup.py
  * added more filters to .gitignore

Change-Id: I792b0244ce9909d70283730a29545304311c6dbc
Felipe Monteiro 1 year ago
parent
commit
a821aeff00
12 changed files with 477 additions and 93 deletions
  1. 105
    0
      .gitignore
  2. 0
    93
      README.md
  3. 105
    0
      README.rst
  4. 0
    0
      docs/source/_static/.placeholder
  5. 155
    0
      docs/source/conf.py
  6. 26
    0
      docs/source/index.rst
  7. 1
    0
      docs/source/readme.rst
  8. 3
    0
      requirements.txt
  9. 30
    0
      setup.cfg
  10. 27
    0
      setup.py
  11. 6
    0
      test-requirements.txt
  12. 19
    0
      tox.ini

+ 105
- 0
.gitignore View File

@@ -1,2 +1,107 @@
1
+# Misc
1 2
 helm.log
2 3
 berth-0.1.0.tgz
4
+
5
+# Byte-compiled / optimized / DLL files
6
+__pycache__/
7
+*.py[cod]
8
+*$py.class
9
+
10
+# C extensions
11
+*.so
12
+
13
+# Distribution / packaging
14
+.Python
15
+env/
16
+build/
17
+develop-eggs/
18
+dist/
19
+downloads/
20
+eggs/
21
+.eggs/
22
+lib/
23
+lib64/
24
+parts/
25
+sdist/
26
+var/
27
+wheels/
28
+*.egg-info/
29
+.installed.cfg
30
+*.egg
31
+
32
+# PyInstaller
33
+#  Usually these files are written by a python script from a template
34
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
35
+*.manifest
36
+*.spec
37
+
38
+# Installer logs
39
+pip-log.txt
40
+pip-delete-this-directory.txt
41
+
42
+# Unit test / coverage reports
43
+htmlcov/
44
+.tox/
45
+.coverage
46
+.coverage.*
47
+.cache
48
+nosetests.xml
49
+coverage.xml
50
+*.cover
51
+.hypothesis/
52
+.testrepository/*
53
+cover/*
54
+
55
+# Translations
56
+*.mo
57
+*.pot
58
+
59
+# Django stuff:
60
+*.log
61
+local_settings.py
62
+
63
+# Flask stuff:
64
+instance/
65
+.webassets-cache
66
+
67
+# Scrapy stuff:
68
+.scrapy
69
+
70
+# Sphinx documentation
71
+docs/_build/
72
+
73
+# PyBuilder
74
+target/
75
+
76
+# Jupyter Notebook
77
+.ipynb_checkpoints
78
+
79
+# pyenv
80
+.python-version
81
+
82
+# celery beat schedule file
83
+celerybeat-schedule
84
+
85
+# SageMath parsed files
86
+*.sage.py
87
+
88
+# dotenv
89
+.env
90
+
91
+# virtualenv
92
+.venv
93
+venv/
94
+ENV/
95
+
96
+# Spyder project settings
97
+.spyderproject
98
+.spyproject
99
+
100
+# Rope project settings
101
+.ropeproject
102
+
103
+# mkdocs documentation
104
+/site
105
+
106
+# mypy
107
+.mypy_cache/

+ 0
- 93
README.md View File

@@ -1,93 +0,0 @@
1
-Berth is a deliberately minimalist VM runner for Kubernetes.
2
-
3
-I'm not 100% sold on the name; before merging we could change it...
4
-
5
-## TL;DR Installation Guide
6
-
7
-```
8
-# Make sure you have Helm 2.5.x and Kubernetes 1.6.x
9
-#
10
-# edit values.yaml; set class_name and ssh key
11
-#
12
-helm package berth
13
-helm install --name=berth ./berth-0.1.0.tgz # ...
14
-kubectl get pods -o wide
15
-```
16
-
17
-You should be able to SSH to your VM at the Kubernetes IP for the
18
-container which you can retrieve with `kubectl get all -o wide`.  VNC
19
-access is available on port 5900.
20
-
21
-```
22
-ssh -i ./you-ssh-private-key root@ip.of.vm.pod
23
-```
24
-<!-- https://mostsecure.pw/  -->
25
-
26
-### Example
27
-
28
-[Quick installation / sample](https://asciinema.org/a/4VazbwsokL3zpnGPf27eyFIfe)
29
-
30
-### Why this?
31
-
32
-The requirements are very narrow right now and the existing
33
-alternatives don't align well at present.  This will likely change in
34
-time at which point we can realign the internal implementation.
35
-
36
-#### Minimalist requirements
37
-* Run VMs from inside of Kubernetes
38
-* Work with Calico
39
-* Have VM life-cycle match that of pods
40
-* Have VMs benefit from Kubernetes resiliency
41
-* Allow for persistent storage
42
-* Allow for state injection/access from a ConfigMaps
43
-
44
-## Requirements:
45
-* Helm 2.5.x
46
-* Kubernetes 1.6.x
47
-
48
-This does not need to be installed as part of the OpenStack chart
49
-collection.
50
-
51
-## How it works:
52
-
53
-At a high level, it works like this:
54
-* Create a SNAT/DNAT enabled linux bridge.
55
-* Assign the bridge a private IP address from a small /30 subnet
56
-  (controlled with `VM_IP` and `VM_GW`)
57
-* Plug the VM network interface into the bridge.
58
-* Run a dnsmasq process to allocate the VM the right name-servers, and
59
-  DNS search strings extracted from the parent container.  Assign the
60
-  private IP address to the VM and have it use the bridges IP as its
61
-  default gateway.
62
-* Setup SNAT/DNAT on the parent container to do 1:1 mapping of all
63
-  ports, all protocols to the VM, except for TCP:5900 to allow for VNC
64
-  access (can be controlled with NO_VNC environment variable).
65
-* At this point, VM essentially assumes Pod Assigned IP.
66
-* Feed any meta-data or user-data down into the VM by leveraging these
67
-  ConfigMap mounts with the same name and turning them into an ISO
68
-  presented to the guest.
69
-
70
-The startvm entry-point supports several environment variables:
71
-
72
-* `IMG_SOURCE` which is an http or https URL that contains a qcow2
73
-  image.  It can also be a full path to a local file baked into the
74
-  container image, e.g. "/image.qcow"
75
-* `IMG_TARGET` the name to save the image above as in the shared
76
-  volume.
77
-
78
-It also supports two files, which should be mounted as ConfigMaps if
79
-using Kubernetes at `/userdata` and `/metadata` as YAML files
80
-containing, obviously meta-data and user-data as YAML that will be fed
81
-to the VM as a config-drive iso.
82
-
83
-The "pet" version of the image, which is created using qemu-img -b to
84
-base it on the source, is stored in a separate volume dedicated to the
85
-VM itself, and named after the container hostname.
86
-
87
-There are a few other parameters you can control as an operator:
88
-
89
-* `VM_IP` is the IP address the VM should be allocated by DHCP.  The
90
-  container will 1:1 NAT except for port 5900 for VNC access (defaults
91
-  to 192.168.254.2)
92
-* `VM_GW` is the gateway IP address the VM should use for its default
93
-  route (defaults to 192.168.254.1)

+ 105
- 0
README.rst View File

@@ -0,0 +1,105 @@
1
+=====
2
+Berth
3
+=====
4
+
5
+Berth is a deliberately minimalist VM runner for Kubernetes.
6
+
7
+I'm not 100% sold on the name; before merging we could change it...
8
+
9
+TL;DR Installation Guide
10
+========================
11
+
12
+.. code-block:: bash
13
+
14
+  # Make sure you have Helm 2.5.x and Kubernetes 1.6.x
15
+  #
16
+  # edit values.yaml; set class_name and ssh key
17
+  #
18
+  helm package berth
19
+  helm install --name=berth ./berth-0.1.0.tgz # ...
20
+  kubectl get pods -o wide
21
+
22
+You should be able to SSH to your VM at the Kubernetes IP for the
23
+container which you can retrieve with `kubectl get all -o wide`.  VNC
24
+access is available on port 5900.
25
+
26
+.. code-block:: bash
27
+
28
+  ssh -i ./you-ssh-private-key root@ip.of.vm.pod
29
+
30
+Example
31
+-------
32
+
33
+`Quick installation / sample <https://asciinema.org/a/4VazbwsokL3zpnGPf27eyFIfe>`_
34
+
35
+Why this?
36
+---------
37
+
38
+The requirements are very narrow right now and the existing
39
+alternatives don't align well at present.  This will likely change in
40
+time at which point we can realign the internal implementation.
41
+
42
+Minimalist requirements
43
+-----------------------
44
+
45
+* Run VMs from inside of Kubernetes
46
+* Work with Calico
47
+* Have VM life-cycle match that of pods
48
+* Have VMs benefit from Kubernetes resiliency
49
+* Allow for persistent storage
50
+* Allow for state injection/access from a ConfigMaps
51
+
52
+Requirements
53
+============
54
+
55
+* Helm 2.5.x
56
+* Kubernetes 1.6.x
57
+
58
+This does not need to be installed as part of the OpenStack chart
59
+collection.
60
+
61
+How it works
62
+============
63
+
64
+At a high level, it works like this:
65
+
66
+  * Create a SNAT/DNAT enabled linux bridge.
67
+  * Assign the bridge a private IP address from a small /30 subnet
68
+    (controlled with `VM_IP` and `VM_GW`)
69
+  * Plug the VM network interface into the bridge.
70
+  * Run a dnsmasq process to allocate the VM the right name-servers, and
71
+    DNS search strings extracted from the parent container.  Assign the
72
+    private IP address to the VM and have it use the bridges IP as its
73
+    default gateway.
74
+  * Setup SNAT/DNAT on the parent container to do 1:1 mapping of all
75
+    ports, all protocols to the VM, except for TCP:5900 to allow for VNC
76
+    access (can be controlled with NO_VNC environment variable).
77
+  * At this point, VM essentially assumes Pod Assigned IP.
78
+  * Feed any meta-data or user-data down into the VM by leveraging these
79
+    ConfigMap mounts with the same name and turning them into an ISO
80
+    presented to the guest.
81
+
82
+The startvm entry-point supports several environment variables:
83
+
84
+  * `IMG_SOURCE` which is an http or https URL that contains a qcow2
85
+    image.  It can also be a full path to a local file baked into the
86
+    container image, e.g. "/image.qcow"
87
+  * `IMG_TARGET` the name to save the image above as in the shared
88
+    volume.
89
+
90
+It also supports two files, which should be mounted as ConfigMaps if
91
+using Kubernetes at `/userdata` and `/metadata` as YAML files
92
+containing, obviously meta-data and user-data as YAML that will be fed
93
+to the VM as a config-drive iso.
94
+
95
+The "pet" version of the image, which is created using qemu-img -b to
96
+base it on the source, is stored in a separate volume dedicated to the
97
+VM itself, and named after the container hostname.
98
+
99
+There are a few other parameters you can control as an operator:
100
+
101
+  * `VM_IP` is the IP address the VM should be allocated by DHCP.  The
102
+    container will 1:1 NAT except for port 5900 for VNC access (defaults
103
+    to 192.168.254.2)
104
+  * `VM_GW` is the gateway IP address the VM should use for its default
105
+    route (defaults to 192.168.254.1)

+ 0
- 0
docs/source/_static/.placeholder View File


+ 155
- 0
docs/source/conf.py View File

@@ -0,0 +1,155 @@
1
+# -*- coding: utf-8 -*-
2
+#
3
+# berth documentation build configuration file, created by
4
+# sphinx-quickstart on Sat Sep 16 03:40:50 2017.
5
+#
6
+# This file is execfile()d with the current directory set to its
7
+# containing dir.
8
+#
9
+# Note that not all possible configuration values are present in this
10
+# autogenerated file.
11
+#
12
+# All configuration values have a default; values that are commented out
13
+# serve to show the default.
14
+
15
+# If extensions (or modules to document with autodoc) are in another directory,
16
+# add these directories to sys.path here. If the directory is relative to the
17
+# documentation root, use os.path.abspath to make it absolute, like shown here.
18
+#
19
+# import os
20
+# import sys
21
+# sys.path.insert(0, os.path.abspath('.'))
22
+
23
+
24
+# -- General configuration ------------------------------------------------
25
+
26
+# If your documentation needs a minimal Sphinx version, state it here.
27
+#
28
+# needs_sphinx = '1.0'
29
+
30
+# Add any Sphinx extension module names here, as strings. They can be
31
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
32
+# ones.
33
+extensions = ['sphinx.ext.autodoc']
34
+
35
+# Add any paths that contain templates here, relative to this directory.
36
+# templates_path = []
37
+
38
+# The suffix(es) of source filenames.
39
+# You can specify multiple suffix as a list of string:
40
+#
41
+# source_suffix = ['.rst', '.md']
42
+source_suffix = '.rst'
43
+
44
+# The master toctree document.
45
+master_doc = 'index'
46
+
47
+# General information about the project.
48
+project = u'Berth'
49
+copyright = u'2017, Berth Authors'
50
+author = u'Berth Authors'
51
+
52
+# The version info for the project you're documenting, acts as replacement for
53
+# |version| and |release|, also used in various other places throughout the
54
+# built documents.
55
+#
56
+# The short X.Y version.
57
+version = u'0.1.0'
58
+# The full version, including alpha/beta/rc tags.
59
+release = u'0.1.0'
60
+
61
+# The language for content autogenerated by Sphinx. Refer to documentation
62
+# for a list of supported languages.
63
+#
64
+# This is also used if you do content translation via gettext catalogs.
65
+# Usually you set "language" from the command line for these cases.
66
+language = None
67
+
68
+# List of patterns, relative to source directory, that match files and
69
+# directories to ignore when looking for source files.
70
+# This patterns also effect to html_static_path and html_extra_path
71
+exclude_patterns = []
72
+
73
+# The name of the Pygments (syntax highlighting) style to use.
74
+pygments_style = 'sphinx'
75
+
76
+# If true, `todo` and `todoList` produce output, else they produce nothing.
77
+todo_include_todos = False
78
+
79
+
80
+# -- Options for HTML output ----------------------------------------------
81
+
82
+# The theme to use for HTML and HTML Help pages.  See the documentation for
83
+# a list of builtin themes.
84
+#
85
+import sphinx_rtd_theme
86
+html_theme = "sphinx_rtd_theme"
87
+html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
88
+
89
+# Theme options are theme-specific and customize the look and feel of a theme
90
+# further.  For a list of options available for each theme, see the
91
+# documentation.
92
+#
93
+# html_theme_options = {}
94
+
95
+# Add any paths that contain custom static files (such as style sheets) here,
96
+# relative to this directory. They are copied after the builtin static files,
97
+# so a file named "default.css" will overwrite the builtin "default.css".
98
+html_static_path = ['_static']
99
+
100
+
101
+# -- Options for HTMLHelp output ------------------------------------------
102
+
103
+# Output file base name for HTML help builder.
104
+htmlhelp_basename = 'berthdoc'
105
+
106
+
107
+# -- Options for LaTeX output ---------------------------------------------
108
+
109
+latex_elements = {
110
+    # The paper size ('letterpaper' or 'a4paper').
111
+    #
112
+    # 'papersize': 'letterpaper',
113
+
114
+    # The font size ('10pt', '11pt' or '12pt').
115
+    #
116
+    # 'pointsize': '10pt',
117
+
118
+    # Additional stuff for the LaTeX preamble.
119
+    #
120
+    # 'preamble': '',
121
+
122
+    # Latex figure (float) alignment
123
+    #
124
+    # 'figure_align': 'htbp',
125
+}
126
+
127
+# Grouping the document tree into LaTeX files. List of tuples
128
+# (source start file, target name, title,
129
+#  author, documentclass [howto, manual, or own class]).
130
+latex_documents = [
131
+    (master_doc, 'berth.tex', u'Berth Documentation',
132
+     u'Berth Authors', 'manual'),
133
+]
134
+
135
+
136
+# -- Options for manual page output ---------------------------------------
137
+
138
+# One entry per manual page. List of tuples
139
+# (source start file, name, description, authors, manual section).
140
+man_pages = [
141
+    (master_doc, 'Berth', u'Berth Documentation',
142
+     [author], 1)
143
+]
144
+
145
+
146
+# -- Options for Texinfo output -------------------------------------------
147
+
148
+# Grouping the document tree into Texinfo files. List of tuples
149
+# (source start file, target name, title, author,
150
+#  dir menu entry, description, category)
151
+texinfo_documents = [
152
+    (master_doc, 'Berth', u'Berth Documentation',
153
+     author, 'Berth', 'A deliberately minimalist VM runner for Kubernetes.',
154
+     'Miscellaneous'),
155
+]

+ 26
- 0
docs/source/index.rst View File

@@ -0,0 +1,26 @@
1
+..
2
+      Copyright 2017 AT&T Intellectual Property.
3
+      All Rights Reserved.
4
+
5
+      Licensed under the Apache License, Version 2.0 (the "License"); you may
6
+      not use this file except in compliance with the License. You may obtain
7
+      a copy of the License at
8
+
9
+          http://www.apache.org/licenses/LICENSE-2.0
10
+
11
+      Unless required by applicable law or agreed to in writing, software
12
+      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
13
+      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
14
+      License for the specific language governing permissions and limitations
15
+      under the License.
16
+
17
+=================================
18
+Welcome to Berth's documentation!
19
+=================================
20
+
21
+Berth is a deliberately minimalist VM runner for Kubernetes.
22
+
23
+.. toctree::
24
+   :maxdepth: 2
25
+
26
+   readme

+ 1
- 0
docs/source/readme.rst View File

@@ -0,0 +1 @@
1
+.. include:: ../../README.rst

+ 3
- 0
requirements.txt View File

@@ -0,0 +1,3 @@
1
+# The order of packages is significant, because pip processes them in the order
2
+# of appearance. Changing the order has an impact on the overall integration
3
+# process, which may cause wedges in the gate later.

+ 30
- 0
setup.cfg View File

@@ -0,0 +1,30 @@
1
+[metadata]
2
+name = Berth
3
+summary = A deliberately minimalist VM runner for Kubernetes.
4
+description-file = README.rst
5
+
6
+author = Berth Authors
7
+home-page = http://berth.readthedocs.io/en/latest/
8
+classifier =
9
+    Intended Audience :: Information Technology
10
+    Intended Audience :: System Administrators
11
+    License :: OSI Approved :: Apache Software License
12
+    Operating System :: POSIX :: Linux
13
+    Programming Language :: Python
14
+    Programming Language :: Python :: 2
15
+    Programming Language :: Python :: 2.7
16
+    Programming Language :: Python :: 3
17
+    Programming Language :: Python :: 3.5
18
+
19
+[files]
20
+packages =
21
+    berth
22
+
23
+[build_sphinx]
24
+source-dir = docs/source
25
+build-dir = docs/build
26
+all_files = 1
27
+warning-is-error = 1
28
+
29
+[upload_sphinx]
30
+upload-dir = doc/build/html

+ 27
- 0
setup.py View File

@@ -0,0 +1,27 @@
1
+# Copyright 2017 AT&T Intellectual Property.  All other rights reserved.
2
+#
3
+# Licensed under the Apache License, Version 2.0 (the "License");
4
+# you may not use this file except in compliance with the License.
5
+# You may obtain a copy of the License at
6
+#
7
+#     http://www.apache.org/licenses/LICENSE-2.0
8
+#
9
+# Unless required by applicable law or agreed to in writing, software
10
+# distributed under the License is distributed on an "AS IS" BASIS,
11
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12
+# See the License for the specific language governing permissions and
13
+# limitations under the License.
14
+
15
+import setuptools
16
+
17
+# In python < 2.7.4, a lazy loading of package `pbr` will break
18
+# setuptools if some other modules registered functions in `atexit`.
19
+# solution from: http://bugs.python.org/issue15881#msg170215
20
+try:
21
+    import multiprocessing  # noqa
22
+except ImportError:
23
+    pass
24
+
25
+setuptools.setup(
26
+    setup_requires=['pbr>=2.0.0'],
27
+    pbr=True)

+ 6
- 0
test-requirements.txt View File

@@ -0,0 +1,6 @@
1
+# The order of packages is significant, because pip processes them in the order
2
+# of appearance. Changing the order has an impact on the overall integration
3
+# process, which may cause wedges in the gate later.
4
+
5
+sphinx>=1.6.2
6
+sphinx_rtd_theme==0.2.4

+ 19
- 0
tox.ini View File

@@ -0,0 +1,19 @@
1
+[tox]
2
+envlist = py35
3
+
4
+[testenv]
5
+usedevelop = True
6
+whitelist_externals = rm
7
+setenv = VIRTUAL_ENV={envdir}
8
+         LANGUAGE=en_US
9
+         LC_ALL=en_US.utf-8
10
+deps = -r{toxinidir}/requirements.txt
11
+       -r{toxinidir}/test-requirements.txt
12
+commands =
13
+  find . -type f -name "*.pyc" -delete
14
+  rm -Rf .testrepository/times.dbm
15
+
16
+[testenv:docs]
17
+commands =
18
+    rm -rf doc/build
19
+    python setup.py build_sphinx {posargs}

Loading…
Cancel
Save