Browse Source

docs update (#32)

* doc improvements
* add picasso images to docs
Derek Schultz 2 years ago
parent
commit
b0a1820cc0

+ 51
- 70
README.md View File

@@ -1,20 +1,15 @@
1
-Picasso: Functions-as-a-Service (FaaS) on OpenStack
2
-===================================================
1
+# Picasso: Functions-as-a-Service (FaaS) on OpenStack
3 2
 
4
-Mission
5
--------
3
+## Mission
6 4
 
7
-Picasso provides an API abstraction layer for Functions-as-a-Service (FaaS) on OpenStack.
5
+Picasso aims to provide an API abstraction layer for Functions-as-a-Service (FaaS) on OpenStack.
8 6
 
9
-Serverless
10
-----------
7
+## What is Serverless/FaaS?
11 8
 
12
-Serverless is a new paradigm in computing that enables simplicity, 
13
-efficiency and scalability for both developers and operators. 
14
-It's important to distinguish the two, because the benefits differ:
9
+Serverless is a new paradigm in computing that enables simplicity, efficiency and scalability for both developers
10
+and operators. It's important to distinguish the two, because the benefits differ:
15 11
 
16
-Benefits for developers
17
------------------------
12
+### Benefits for developers
18 13
 
19 14
 The main benefits that most people refer to are on the developer side and they include:
20 15
 
@@ -23,8 +18,10 @@ The main benefits that most people refer to are on the developer side and they i
23 18
 * Pay by the milliseconds your code is executing -- unlike a typical application that runs 24/7, and you're paying
24 19
   24/7, functions only run when needed
25 20
 
26
-Benefits for operators
27
-----------------------
21
+Since you'll be running IronFunctions yourself, the paying part may not apply, but it does apply to
22
+cost savings on your infrastructure bills as you'll read below.
23
+
24
+### Benefits for operators
28 25
 
29 26
 If you will be operating IronFunctions (the person who has to manage the servers behind the serverless),
30 27
 then the benefits are different, but related.
@@ -39,61 +36,54 @@ then the benefits are different, but related.
39 36
   * Scaling is the same for all functions, you don't scale each app independently
40 37
   * Scaling is simply adding more IronFunctions nodes
41 38
 
42
-System requirements
43
--------------------
39
+
40
+### System requirements
44 41
 
45 42
 * Operating system: Linux/MacOS
46 43
 * Python version: 3.5 or greater
47 44
 * Database: MySQL 5.7 or greater
48 45
 
49
-Quick-start guide
50
------------------
46
+### Quick-start guide
51 47
 
52
-Install DevStack with [IronFunctions enabled](https://github.com/iron-io/functions-devstack-plugin/blob/master/README.rst).
53
-Pull down [Picasso sources](https://github.com/iron-io/project-picasso).
48
+* Install DevStack with [IronFunctions enabled](https://github.com/iron-io/picasso/blob/master/devstack/README.rst)
49
+* Clone the [Picasso source](https://github.com/iron-io/picasso)
54 50
 
55
-Create Python3.5 virtualenv:
51
+Create a Python3.5 virtualenv
56 52
 
57 53
     $ virtualenv -p python3.5 .venv
58 54
     $ source .venv/bin/activate
59 55
 
60
-Install dependencies:
56
+Install dependencies
61 57
 
62 58
     $ pip install -r requirements.txt -r test-requirements.txt
63 59
 
64
-Install Picasso itself:
60
+Install Picasso
65 61
 
66 62
     $ pip install -e .
67 63
 
68
-Install MySQL if you haven't already, and create a new database for functions.
64
+Install MySQL if you haven't already, and create a new database for functions
69 65
 
70 66
     $ mysql -uroot -p -e "CREATE DATABASE functions"
71 67
 
68
+### Migrations
72 69
 
73
-Migrations
74
-----------
75
-
76
-Once all dependencies are installed it is necessary to run database migrations.
77
-Before that it is necessary to set env variable:
70
+Once all dependencies are installed it is necessary to run database migrations. First,
71
+set the following environment variable:
78 72
 
79 73
     export PICASSO_MIGRATIONS_DB=mysql+pymysql://root:root@localhost/functions
80 74
 
81
-In this section please specify connection URI to your own MySQL database.
82
-Once the file is saved, just use alembic to apply the migrations:
75
+Use `alembic` to apply the migrations:
83 76
 
84 77
     $ alembic upgrade head
85 78
 
86
-Starting a server
87
------------------
88
-
89
-Once it is finished you will have a console script `picasso-api`:
79
+### Starting the Picasso API server
90 80
 
91 81
     $ picasso-api --help
92 82
 
93 83
     Usage: picasso-api [OPTIONS]
94
-    
84
+
95 85
       Starts Picasso API service
96
-    
86
+
97 87
     Options:
98 88
       --host TEXT                    API service bind host.
99 89
       --port INTEGER                 API service bind port.
@@ -104,45 +94,43 @@ Once it is finished you will have a console script `picasso-api`:
104 94
       --log-file TEXT                Log file path
105 95
       --help                         Show this message and exit.
106 96
 
107
-Minimum required options to start Picasso API service:
97
+The following are the minimum required options to start the Picasso API service:
108 98
 
109 99
      --db-uri mysql://root:root@192.168.0.112/functions
110 100
      --keystone-endpoint http://192.168.0.112:5000/v3
111 101
      --functions-url http://192.168.0.112:8080/v1
112 102
      --log-level INFO
113 103
 
114
-Creating and running Picasso inside Docker container
115
--------------------------------------------------
116
-
117
-As part of regular Python distribution, Picasso also has its own Docker container to run.
118
-There are two options:
104
+### Building and Running Picasso in Docker
119 105
 
120
-* run from sources
121
-* run from Docker Hub
122
-
123
-In order to build container from sources run following commands:
106
+From the Picasso repo, build a Docker image:
124 107
 
125 108
     export DOCKER_HOST=tcp://<docker-host>:<docker-port>
126 109
     docker build -t picasso-api -f Dockerfile .
127 110
 
128
-After that it is required to create correct version of [Dockerfile.env](Dockerfile.env.example). 
129
-It container all required options to start Picasso API service properly.
130
-Once it is done run following commands:
111
+To start the container, pass in the required env vars, by
112
+
113
+`--env-file` example [Dockerfile.env](Dockerfile.env.example)
114
+
115
+     docker run -d -p 10001:10001 --env-file Dockerfile.env picasso-api
116
+
117
+or by entering all values in `-e <KEY>=<VALUE>` format.
131 118
 
132
-    docker run -d -p 10001:10001 --env-file Dockerfile.env picasso-api
119
+Once the container is started, check if the service in running:
133 120
 
134
-Navigate to your web browser to check if service is running:
121
+In your web browser navigate to:
135 122
 
136 123
     <docker-host>:10001/api
137 124
 
138
-or using CLI
125
+or using the CLI:
139 126
 
140 127
     curl -X GET http://<docker-host>:10001/api/swagger.json | python -mjson.tool
141 128
 
142
-Examining API
143
--------------
129
+### Examining the API
144 130
 
145
-In [examples](examples/) folder you can find a script that examines available API endpoints, but this script relays on:
131
+In [examples](examples/) folder you can find a script that examines available API endpoints.
132
+
133
+Note that this script depends on the following env vars:
146 134
 
147 135
 * `PICASSO_API_URL` - Picasso API endpoint
148 136
 * `OS_AUTH_URL` - OpenStack Auth URL
@@ -152,27 +140,20 @@ In [examples](examples/) folder you can find a script that examines available AP
152 140
 * `OS_DOMAIN` - OpenStack project domain name
153 141
 * `OS_PROJECT_NAME` - OpenStack project name
154 142
 
155
-Then just run script:
143
+To run the script:
156 144
 
157 145
     OS_AUTH_URL=http://192.168.0.112:5000/v3 OS_PROJECT_ID=8fb76785313a4500ac5367eb44a31677 OS_USERNAME=admin OS_PASSWORD=root OS_DOMAIN=default OS_PROJECT_NAME=admin ./examples/hello-lambda.sh
158 146
 
159
-Please note, that given values are project-specific, so they can't be reused.
147
+Please note that values provided are project-specific, so they can't be reused.
160 148
 
161
-API docs
162
---------
149
+### API docs
163 150
 
164
-As part of Picasso ReST API it is possible to discover API doc using Swagger Doc.
165
-Once server is launched you can navigate to:
151
+API docs are discoverable via Swagger. Just launch the Picasso API and browse to:
166 152
 
167 153
     http://<picasso-host>:<picasso-port>/api
168 154
 
169
-to see recent API docs
170
-
171
-
172
-Contacts
173
---------
155
+### Support
174 156
 
175
-Feel free to reach us out at:
157
+You can get community support via:
176 158
 
177
-* [Slack channel](https://open-iron.herokuapp.com/)
178
-* [Email](https://github.com/denismakogon)
159
+    * [Slack](https://open-iron.herokuapp.com/)

+ 216
- 0
docs/Makefile View File

@@ -0,0 +1,216 @@
1
+# Makefile for Sphinx documentation
2
+#
3
+
4
+# You can set these variables from the command line.
5
+SPHINXOPTS    =
6
+SPHINXBUILD   = sphinx-build
7
+PAPER         =
8
+BUILDDIR      = build
9
+
10
+# User-friendly check for sphinx-build
11
+ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
12
+$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
13
+endif
14
+
15
+# Internal variables.
16
+PAPEROPT_a4     = -D latex_paper_size=a4
17
+PAPEROPT_letter = -D latex_paper_size=letter
18
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
19
+# the i18n builder cannot share the environment and doctrees with the others
20
+I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
21
+
22
+.PHONY: help
23
+help:
24
+	@echo "Please use \`make <target>' where <target> is one of"
25
+	@echo "  html       to make standalone HTML files"
26
+	@echo "  dirhtml    to make HTML files named index.html in directories"
27
+	@echo "  singlehtml to make a single large HTML file"
28
+	@echo "  pickle     to make pickle files"
29
+	@echo "  json       to make JSON files"
30
+	@echo "  htmlhelp   to make HTML files and a HTML help project"
31
+	@echo "  qthelp     to make HTML files and a qthelp project"
32
+	@echo "  applehelp  to make an Apple Help Book"
33
+	@echo "  devhelp    to make HTML files and a Devhelp project"
34
+	@echo "  epub       to make an epub"
35
+	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
36
+	@echo "  latexpdf   to make LaTeX files and run them through pdflatex"
37
+	@echo "  latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
38
+	@echo "  text       to make text files"
39
+	@echo "  man        to make manual pages"
40
+	@echo "  texinfo    to make Texinfo files"
41
+	@echo "  info       to make Texinfo files and run them through makeinfo"
42
+	@echo "  gettext    to make PO message catalogs"
43
+	@echo "  changes    to make an overview of all changed/added/deprecated items"
44
+	@echo "  xml        to make Docutils-native XML files"
45
+	@echo "  pseudoxml  to make pseudoxml-XML files for display purposes"
46
+	@echo "  linkcheck  to check all external links for integrity"
47
+	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
48
+	@echo "  coverage   to run coverage check of the documentation (if enabled)"
49
+
50
+.PHONY: clean
51
+clean:
52
+	rm -rf $(BUILDDIR)/*
53
+
54
+.PHONY: html
55
+html:
56
+	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
57
+	@echo
58
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
59
+
60
+.PHONY: dirhtml
61
+dirhtml:
62
+	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
63
+	@echo
64
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
65
+
66
+.PHONY: singlehtml
67
+singlehtml:
68
+	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
69
+	@echo
70
+	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
71
+
72
+.PHONY: pickle
73
+pickle:
74
+	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
75
+	@echo
76
+	@echo "Build finished; now you can process the pickle files."
77
+
78
+.PHONY: json
79
+json:
80
+	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
81
+	@echo
82
+	@echo "Build finished; now you can process the JSON files."
83
+
84
+.PHONY: htmlhelp
85
+htmlhelp:
86
+	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
87
+	@echo
88
+	@echo "Build finished; now you can run HTML Help Workshop with the" \
89
+	      ".hhp project file in $(BUILDDIR)/htmlhelp."
90
+
91
+.PHONY: qthelp
92
+qthelp:
93
+	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
94
+	@echo
95
+	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
96
+	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
97
+	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/Picasso.qhcp"
98
+	@echo "To view the help file:"
99
+	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/Picasso.qhc"
100
+
101
+.PHONY: applehelp
102
+applehelp:
103
+	$(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp
104
+	@echo
105
+	@echo "Build finished. The help book is in $(BUILDDIR)/applehelp."
106
+	@echo "N.B. You won't be able to view it unless you put it in" \
107
+	      "~/Library/Documentation/Help or install it in your application" \
108
+	      "bundle."
109
+
110
+.PHONY: devhelp
111
+devhelp:
112
+	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
113
+	@echo
114
+	@echo "Build finished."
115
+	@echo "To view the help file:"
116
+	@echo "# mkdir -p $$HOME/.local/share/devhelp/Picasso"
117
+	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/Picasso"
118
+	@echo "# devhelp"
119
+
120
+.PHONY: epub
121
+epub:
122
+	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
123
+	@echo
124
+	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
125
+
126
+.PHONY: latex
127
+latex:
128
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
129
+	@echo
130
+	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
131
+	@echo "Run \`make' in that directory to run these through (pdf)latex" \
132
+	      "(use \`make latexpdf' here to do that automatically)."
133
+
134
+.PHONY: latexpdf
135
+latexpdf:
136
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
137
+	@echo "Running LaTeX files through pdflatex..."
138
+	$(MAKE) -C $(BUILDDIR)/latex all-pdf
139
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
140
+
141
+.PHONY: latexpdfja
142
+latexpdfja:
143
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
144
+	@echo "Running LaTeX files through platex and dvipdfmx..."
145
+	$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
146
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
147
+
148
+.PHONY: text
149
+text:
150
+	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
151
+	@echo
152
+	@echo "Build finished. The text files are in $(BUILDDIR)/text."
153
+
154
+.PHONY: man
155
+man:
156
+	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
157
+	@echo
158
+	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
159
+
160
+.PHONY: texinfo
161
+texinfo:
162
+	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
163
+	@echo
164
+	@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
165
+	@echo "Run \`make' in that directory to run these through makeinfo" \
166
+	      "(use \`make info' here to do that automatically)."
167
+
168
+.PHONY: info
169
+info:
170
+	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
171
+	@echo "Running Texinfo files through makeinfo..."
172
+	make -C $(BUILDDIR)/texinfo info
173
+	@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
174
+
175
+.PHONY: gettext
176
+gettext:
177
+	$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
178
+	@echo
179
+	@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
180
+
181
+.PHONY: changes
182
+changes:
183
+	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
184
+	@echo
185
+	@echo "The overview file is in $(BUILDDIR)/changes."
186
+
187
+.PHONY: linkcheck
188
+linkcheck:
189
+	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
190
+	@echo
191
+	@echo "Link check complete; look for any errors in the above output " \
192
+	      "or in $(BUILDDIR)/linkcheck/output.txt."
193
+
194
+.PHONY: doctest
195
+doctest:
196
+	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
197
+	@echo "Testing of doctests in the sources finished, look at the " \
198
+	      "results in $(BUILDDIR)/doctest/output.txt."
199
+
200
+.PHONY: coverage
201
+coverage:
202
+	$(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage
203
+	@echo "Testing of coverage in the sources finished, look at the " \
204
+	      "results in $(BUILDDIR)/coverage/python.txt."
205
+
206
+.PHONY: xml
207
+xml:
208
+	$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
209
+	@echo
210
+	@echo "Build finished. The XML files are in $(BUILDDIR)/xml."
211
+
212
+.PHONY: pseudoxml
213
+pseudoxml:
214
+	$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
215
+	@echo
216
+	@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."

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

@@ -0,0 +1,285 @@
1
+#!/usr/bin/env python3
2
+# -*- coding: utf-8 -*-
3
+#
4
+# Picasso documentation build configuration file, created by
5
+# sphinx-quickstart on Thu Nov 24 13:24:43 2016.
6
+#
7
+# This file is execfile()d with the current directory set to its
8
+# containing dir.
9
+#
10
+# Note that not all possible configuration values are present in this
11
+# autogenerated file.
12
+#
13
+# All configuration values have a default; values that are commented out
14
+# serve to show the default.
15
+
16
+import sys
17
+import os
18
+
19
+# If extensions (or modules to document with autodoc) are in another directory,
20
+# add these directories to sys.path here. If the directory is relative to the
21
+# documentation root, use os.path.abspath to make it absolute, like shown here.
22
+#sys.path.insert(0, os.path.abspath('.'))
23
+
24
+# -- General configuration ------------------------------------------------
25
+
26
+# If your documentation needs a minimal Sphinx version, state it here.
27
+#needs_sphinx = '1.0'
28
+
29
+# Add any Sphinx extension module names here, as strings. They can be
30
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
31
+# ones.
32
+extensions = [
33
+    'sphinx.ext.coverage',
34
+]
35
+
36
+# Add any paths that contain templates here, relative to this directory.
37
+templates_path = ['_templates']
38
+
39
+# The suffix(es) of source filenames.
40
+# You can specify multiple suffix as a list of string:
41
+# source_suffix = ['.rst', '.md']
42
+source_suffix = '.rst'
43
+
44
+# The encoding of source files.
45
+#source_encoding = 'utf-8-sig'
46
+
47
+# The master toctree document.
48
+master_doc = 'index'
49
+
50
+# General information about the project.
51
+project = 'Picasso'
52
+copyright = '2016, Iron.io'
53
+author = 'Iron.io'
54
+
55
+# The version info for the project you're documenting, acts as replacement for
56
+# |version| and |release|, also used in various other places throughout the
57
+# built documents.
58
+#
59
+# The short X.Y version.
60
+version = '0.0.1'
61
+# The full version, including alpha/beta/rc tags.
62
+release = '0.0.1'
63
+
64
+# The language for content autogenerated by Sphinx. Refer to documentation
65
+# for a list of supported languages.
66
+#
67
+# This is also used if you do content translation via gettext catalogs.
68
+# Usually you set "language" from the command line for these cases.
69
+language = None
70
+
71
+# There are two options for replacing |today|: either, you set today to some
72
+# non-false value, then it is used:
73
+#today = ''
74
+# Else, today_fmt is used as the format for a strftime call.
75
+#today_fmt = '%B %d, %Y'
76
+
77
+# List of patterns, relative to source directory, that match files and
78
+# directories to ignore when looking for source files.
79
+exclude_patterns = []
80
+
81
+# The reST default role (used for this markup: `text`) to use for all
82
+# documents.
83
+#default_role = None
84
+
85
+# If true, '()' will be appended to :func: etc. cross-reference text.
86
+#add_function_parentheses = True
87
+
88
+# If true, the current module name will be prepended to all description
89
+# unit titles (such as .. function::).
90
+#add_module_names = True
91
+
92
+# If true, sectionauthor and moduleauthor directives will be shown in the
93
+# output. They are ignored by default.
94
+#show_authors = False
95
+
96
+# The name of the Pygments (syntax highlighting) style to use.
97
+pygments_style = 'sphinx'
98
+
99
+# A list of ignored prefixes for module index sorting.
100
+#modindex_common_prefix = []
101
+
102
+# If true, keep warnings as "system message" paragraphs in the built documents.
103
+#keep_warnings = False
104
+
105
+# If true, `todo` and `todoList` produce output, else they produce nothing.
106
+todo_include_todos = False
107
+
108
+
109
+# -- Options for HTML output ----------------------------------------------
110
+
111
+# The theme to use for HTML and HTML Help pages.  See the documentation for
112
+# a list of builtin themes.
113
+html_theme = 'alabaster'
114
+
115
+# Theme options are theme-specific and customize the look and feel of a theme
116
+# further.  For a list of options available for each theme, see the
117
+# documentation.
118
+#html_theme_options = {}
119
+
120
+# Add any paths that contain custom themes here, relative to this directory.
121
+#html_theme_path = []
122
+
123
+# The name for this set of Sphinx documents.  If None, it defaults to
124
+# "<project> v<release> documentation".
125
+#html_title = None
126
+
127
+# A shorter title for the navigation bar.  Default is the same as html_title.
128
+#html_short_title = None
129
+
130
+# The name of an image file (relative to this directory) to place at the top
131
+# of the sidebar.
132
+#html_logo = None
133
+
134
+# The name of an image file (relative to this directory) to use as a favicon of
135
+# the docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
136
+# pixels large.
137
+#html_favicon = None
138
+
139
+# Add any paths that contain custom static files (such as style sheets) here,
140
+# relative to this directory. They are copied after the builtin static files,
141
+# so a file named "default.css" will overwrite the builtin "default.css".
142
+html_static_path = ['_static']
143
+
144
+# Add any extra paths that contain custom files (such as robots.txt or
145
+# .htaccess) here, relative to this directory. These files are copied
146
+# directly to the root of the documentation.
147
+#html_extra_path = []
148
+
149
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
150
+# using the given strftime format.
151
+#html_last_updated_fmt = '%b %d, %Y'
152
+
153
+# If true, SmartyPants will be used to convert quotes and dashes to
154
+# typographically correct entities.
155
+#html_use_smartypants = True
156
+
157
+# Custom sidebar templates, maps document names to template names.
158
+#html_sidebars = {}
159
+
160
+# Additional templates that should be rendered to pages, maps page names to
161
+# template names.
162
+#html_additional_pages = {}
163
+
164
+# If false, no module index is generated.
165
+#html_domain_indices = True
166
+
167
+# If false, no index is generated.
168
+#html_use_index = True
169
+
170
+# If true, the index is split into individual pages for each letter.
171
+#html_split_index = False
172
+
173
+# If true, links to the reST sources are added to the pages.
174
+#html_show_sourcelink = True
175
+
176
+# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
177
+#html_show_sphinx = True
178
+
179
+# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
180
+#html_show_copyright = True
181
+
182
+# If true, an OpenSearch description file will be output, and all pages will
183
+# contain a <link> tag referring to it.  The value of this option must be the
184
+# base URL from which the finished HTML is served.
185
+#html_use_opensearch = ''
186
+
187
+# This is the file name suffix for HTML files (e.g. ".xhtml").
188
+#html_file_suffix = None
189
+
190
+# Language to be used for generating the HTML full-text search index.
191
+# Sphinx supports the following languages:
192
+#   'da', 'de', 'en', 'es', 'fi', 'fr', 'h', 'it', 'ja'
193
+#   'nl', 'no', 'pt', 'ro', 'r', 'sv', 'tr'
194
+#html_search_language = 'en'
195
+
196
+# A dictionary with options for the search language support, empty by default.
197
+# Now only 'ja' uses this config value
198
+#html_search_options = {'type': 'default'}
199
+
200
+# The name of a javascript file (relative to the configuration directory) that
201
+# implements a search results scorer. If empty, the default will be used.
202
+#html_search_scorer = 'scorer.js'
203
+
204
+# Output file base name for HTML help builder.
205
+htmlhelp_basename = 'Picassodoc'
206
+
207
+# -- Options for LaTeX output ---------------------------------------------
208
+
209
+latex_elements = {
210
+# The paper size ('letterpaper' or 'a4paper').
211
+#'papersize': 'letterpaper',
212
+
213
+# The font size ('10pt', '11pt' or '12pt').
214
+#'pointsize': '10pt',
215
+
216
+# Additional stuff for the LaTeX preamble.
217
+#'preamble': '',
218
+
219
+# Latex figure (float) alignment
220
+#'figure_align': 'htbp',
221
+}
222
+
223
+# Grouping the document tree into LaTeX files. List of tuples
224
+# (source start file, target name, title,
225
+#  author, documentclass [howto, manual, or own class]).
226
+latex_documents = [
227
+    (master_doc, 'Picasso.tex', 'Picasso Documentation', 'manual'),
228
+]
229
+
230
+# The name of an image file (relative to this directory) to place at the top of
231
+# the title page.
232
+#latex_logo = None
233
+
234
+# For "manual" documents, if this is true, then toplevel headings are parts,
235
+# not chapters.
236
+#latex_use_parts = False
237
+
238
+# If true, show page references after internal links.
239
+#latex_show_pagerefs = False
240
+
241
+# If true, show URL addresses after external links.
242
+#latex_show_urls = False
243
+
244
+# Documents to append as an appendix to all manuals.
245
+#latex_appendices = []
246
+
247
+# If false, no module index is generated.
248
+#latex_domain_indices = True
249
+
250
+
251
+# -- Options for manual page output ---------------------------------------
252
+
253
+# One entry per manual page. List of tuples
254
+# (source start file, name, description, authors, manual section).
255
+man_pages = [
256
+    (master_doc, 'picasso', 'Picasso Documentation',
257
+     [author], 1)
258
+]
259
+
260
+# If true, show URL addresses after external links.
261
+#man_show_urls = False
262
+
263
+
264
+# -- Options for Texinfo output -------------------------------------------
265
+
266
+# Grouping the document tree into Texinfo files. List of tuples
267
+# (source start file, target name, title, author,
268
+#  dir menu entry, description, category)
269
+texinfo_documents = [
270
+    (master_doc, 'Picasso', 'Picasso Documentation',
271
+     author, 'Picasso', 'One line description of project.',
272
+     'Miscellaneous'),
273
+]
274
+
275
+# Documents to append as an appendix to all manuals.
276
+#texinfo_appendices = []
277
+
278
+# If false, no module index is generated.
279
+#texinfo_domain_indices = True
280
+
281
+# How to display URL addresses: 'footnote', 'no', or 'inline'.
282
+#texinfo_show_urls = 'footnote'
283
+
284
+# If true, do not generate a @detailmenu in the "Top" node's menu.
285
+#texinfo_no_detailmenu = False

+ 84
- 0
docs/source/deployment_guide.rst View File

@@ -0,0 +1,84 @@
1
+*****************************
2
+Picasso deployment guide
3
+*****************************
4
+
5
+
6
+DevStack
7
+########
8
+
9
+See full install guide in devstack_plugin_
10
+
11
+Existing OpenStack
12
+##################
13
+
14
+Required software::
15
+
16
+* Python 3.5 or greater
17
+* Go 1.7 or greater
18
+* Glide
19
+* OpenStack Identity (Keystone)
20
+* Docker (single instance or clustered)
21
+
22
+Software that will be installed::
23
+
24
+* IronFunctions
25
+* Picasso
26
+
27
+
28
+IronFunctions installation
29
+**************************
30
+
31
+IronFunctions is a core component of Picasso that interacts with the Docker API.
32
+
33
+Run the following commands to install IronFunctions::
34
+
35
+    export GOPATH=~/go
36
+    export FUNCTIONS_DIR=$GOPATH/src/github.com/iron-io/functions
37
+    mkdir -p $FUNCTIONS_DIR
38
+    pushd $FUNCTIONS_DIR && GOPATH=${GOPATH} make all; popd
39
+
40
+Running ``$FUNCTIONS_DIR/functions`` will start IronFunctions using an embedded Bolt database running on port 8080.
41
+
42
+See IronFunctions configuration options_
43
+
44
+Installing Picasso
45
+******************
46
+
47
+Picasso is a lightweight ReST API service to work with IronFunctions using the OpenStack Identity (Keystone) model.
48
+
49
+
50
+Run the following commands to install Picasso::
51
+
52
+
53
+    git clone git@github.com:iron-io/picasso.git
54
+    pip3 install -r requirements.txt
55
+    pip3 install -e .
56
+
57
+Review the Picasso README_ for how to get started.
58
+
59
+OpenStack Identity (Keystone) configuration
60
+*******************************************
61
+
62
+Create a new ``functions`` service in Keystone using the OpenStack_CLI_
63
+This will enable the Picasso API by resolving its endpoint through the service catalog.
64
+
65
+Running IronFunctions in production
66
+***********************************
67
+
68
+From a deployment perspective IronFunctions is nothing more than an internal service, so its API should not be exposed to OpenStack users.
69
+
70
+Running Picasso in production
71
+*****************************
72
+
73
+Required software::
74
+
75
+    Load balancer such as HaProxy or Nginx
76
+
77
+
78
+The Picasso API endpoint should be available to OpenStack users, therefore it is suggested to run the API behind a load balancer.
79
+
80
+.. _devstack_plugin: https://github.com/iron-io/picasso/blob/master/devstack/README.rst
81
+.. _Glide: https://github.com/Masterminds/glide
82
+.. _options: https://github.com/iron-io/functions/blob/master/docs/options.md
83
+.. _README: https://github.com/iron-io/picasso/blob/master/README.md
84
+.. _OpenStack_CLI: http://docs.openstack.org/cli-reference/

+ 62
- 0
docs/source/functions.rst View File

@@ -0,0 +1,62 @@
1
+*********
2
+Functions
3
+*********
4
+
5
+
6
+Writing functions
7
+*****************
8
+
9
+What is a function?
10
+###################
11
+
12
+Functions are small, bite sized bits of code that do one simple thing. Forget about
13
+monoliths when using functions, just focus on the task that you want the function to perform.
14
+
15
+Unlike an app/API/microservice that consumes resources 24/7 whether they are in use or not,
16
+functions are time sliced across your infrastructure and only consume resources while they are
17
+actually doing something.
18
+
19
+Function composition
20
+#####################
21
+At a high-level, functions are comprised of applications and routes::
22
+
23
+    An application is essentially a grouping of functions, that put together, form an API.
24
+
25
+    A route is a way to define a path in your application that maps to a function.
26
+
27
+Calling your function is as simple as requesting a URL. Each app has it's own namespace and
28
+each route mapped to the app.
29
+
30
+How are functions packaged?
31
+###########################
32
+
33
+Packaging a function has two parts:
34
+
35
+Create a Docker image for your function with an ``ENTRYPOINT``::
36
+
37
+    Push your Docker image to a registry (Docker Hub by default).
38
+    
39
+    Once it's pushed to a registry, you can use it by referencing it when adding a route.
40
+
41
+Writing functions
42
+#################
43
+
44
+See the IronFunctions guide_ on writing functions.
45
+
46
+What functions can do
47
+######################
48
+
49
+As functions are essentially just containers, anything that runs in a container can be a function.
50
+Functions typically useful for short-lived tasks, such as:
51
+
52
+    * Data processing
53
+    * ETL
54
+
55
+
56
+What functions cannot do
57
+########################
58
+
59
+Long running processes are not intended for functions.
60
+
61
+
62
+.. _guide: https://github.com/iron-io/functions/blob/master/docs/writing.md

BIN
docs/source/images/intercomponent_architecture.png View File


BIN
docs/source/images/picasso_deployment.png View File


BIN
docs/source/images/telemetry_use_case.png View File


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

@@ -0,0 +1,23 @@
1
+.. Picasso documentation master file, created by
2
+   sphinx-quickstart on Thu Nov 24 13:24:43 2016.
3
+   You can adapt this file completely to your liking, but it should at least
4
+   contain the root `toctree` directive.
5
+
6
+Welcome to Picasso documentation!
7
+========================================
8
+
9
+Contents:
10
+
11
+.. toctree::
12
+   :maxdepth: 2
13
+
14
+   deployment_guide.rst
15
+   functions.rst
16
+
17
+
18
+Indices and tables
19
+==================
20
+
21
+* :ref:`genindex`
22
+* :ref:`modindex`
23
+* :ref:`search`

+ 2
- 2
tox.ini View File

@@ -1,4 +1,4 @@
1
-# Project LaOS
1
+# Picasso
2 2
 
3 3
 [tox]
4 4
 envlist = py35-functional,py35-functional-regression,py35-integration,py35-integration-regression,pep8,docker-build,bandit
@@ -57,4 +57,4 @@ commands = bandit -r picasso/
57 57
 [flake8]
58 58
 ignore = H202,H304,H404,H405,H501
59 59
 show-source = True
60
-exclude=.venv,.git,.tox,dist,doc,*lib/python*,*egg,build,migrations
60
+exclude=.venv,.git,.tox,dist,doc,*lib/python*,*egg,build,migrations,docs

Loading…
Cancel
Save