Skip to content

Commit 70d6a5f

Browse files
author
Phil Rzewski
committed
Start transitioning documentation to Sphinx/docstrings
1 parent 437a117 commit 70d6a5f

File tree

5 files changed

+321
-0
lines changed

5 files changed

+321
-0
lines changed

‎doc/Makefile‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
# Minimal makefile for Sphinx documentation
2+
#
3+
4+
# You can set these variables from the command line.
5+
SPHINXOPTS =
6+
SPHINXBUILD = sphinx-build
7+
SPHINXPROJ = python-sdc-client
8+
SOURCEDIR = .
9+
BUILDDIR = _build
10+
11+
# Put it first so that "make" without argument is like "make help".
12+
help:
13+
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
14+
15+
.PHONY: help Makefile
16+
17+
# Catch-all target: route all unknown targets to Sphinx using the new
18+
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
19+
%: Makefile
20+
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
21+

‎doc/conf.py‎

Lines changed: 156 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,156 @@
1+
# -*- coding: utf-8 -*-
2+
#
3+
# python-sdc-client documentation build configuration file, created by
4+
# sphinx-quickstart on Thu Dec 22 11:59:02 2016.
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 = ['_templates']
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'python-sdc-client'
49+
copyright = u'2016, Sysdig Inc.'
50+
author = u'Sysdig Inc.'
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''
58+
# The full version, including alpha/beta/rc tags.
59+
release = u''
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 = ['_build', 'Thumbs.db', '.DS_Store']
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+
html_theme = 'classic'
86+
87+
# Theme options are theme-specific and customize the look and feel of a theme
88+
# further. For a list of options available for each theme, see the
89+
# documentation.
90+
#
91+
# html_theme_options = {}
92+
93+
# Add any paths that contain custom static files (such as style sheets) here,
94+
# relative to this directory. They are copied after the builtin static files,
95+
# so a file named "default.css" will overwrite the builtin "default.css".
96+
html_static_path = ['_static']
97+
98+
99+
# -- Options for HTMLHelp output ------------------------------------------
100+
101+
# Output file base name for HTML help builder.
102+
htmlhelp_basename = 'python-sdc-clientdoc'
103+
104+
105+
# -- Options for LaTeX output ---------------------------------------------
106+
107+
latex_elements = {
108+
# The paper size ('letterpaper' or 'a4paper').
109+
#
110+
# 'papersize': 'letterpaper',
111+
112+
# The font size ('10pt', '11pt' or '12pt').
113+
#
114+
# 'pointsize': '10pt',
115+
116+
# Additional stuff for the LaTeX preamble.
117+
#
118+
# 'preamble': '',
119+
120+
# Latex figure (float) alignment
121+
#
122+
# 'figure_align': 'htbp',
123+
}
124+
125+
# Grouping the document tree into LaTeX files. List of tuples
126+
# (source start file, target name, title,
127+
# author, documentclass [howto, manual, or own class]).
128+
latex_documents = [
129+
(master_doc, 'python-sdc-client.tex', u'python-sdc-client Documentation',
130+
u'Sysdig Inc.', 'manual'),
131+
]
132+
133+
134+
# -- Options for manual page output ---------------------------------------
135+
136+
# One entry per manual page. List of tuples
137+
# (source start file, name, description, authors, manual section).
138+
man_pages = [
139+
(master_doc, 'python-sdc-client', u'python-sdc-client Documentation',
140+
[author], 1)
141+
]
142+
143+
144+
# -- Options for Texinfo output -------------------------------------------
145+
146+
# Grouping the document tree into Texinfo files. List of tuples
147+
# (source start file, target name, title, author,
148+
# dir menu entry, description, category)
149+
texinfo_documents = [
150+
(master_doc, 'python-sdc-client', u'python-sdc-client Documentation',
151+
author, 'python-sdc-client', 'One line description of project.',
152+
'Miscellaneous'),
153+
]
154+
155+
156+

‎doc/index.rst‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
.. python-sdc-client documentation master file, created by
2+
sphinx-quickstart on Thu Dec 22 11:59:02 2016.
3+
You can adapt this file completely to your liking, but it should at least
4+
contain the root `toctree` directive.
5+
6+
Python Script Library
7+
=====================
8+
9+
* :ref:`genindex`
10+
* :ref:`search`
11+
12+
13+
14+
Function List
15+
=============
16+
.. autoclass:: sdcclient._client.SdcClient
17+
:members:
18+
:undoc-members:

‎doc/make.bat‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
@ECHO OFF
2+
3+
pushd %~dp0
4+
5+
REM Command file for Sphinx documentation
6+
7+
if "%SPHINXBUILD%" == "" (
8+
set SPHINXBUILD=sphinx-build
9+
)
10+
set SOURCEDIR=.
11+
set BUILDDIR=_build
12+
set SPHINXPROJ=python-sdc-client
13+
14+
if "%1" == "" goto help
15+
16+
%SPHINXBUILD% >NUL 2>NUL
17+
if errorlevel 9009 (
18+
echo.
19+
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
20+
echo.installed, then set the SPHINXBUILD environment variable to point
21+
echo.to the full path of the 'sphinx-build' executable. Alternatively you
22+
echo.may add the Sphinx directory to PATH.
23+
echo.
24+
echo.If you don't have Sphinx installed, grab it from
25+
echo.http://sphinx-doc.org/
26+
exit /b 1
27+
)
28+
29+
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
30+
goto end
31+
32+
:help
33+
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
34+
35+
:end
36+
popd

‎sdcclient/_client.py‎

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -151,6 +151,28 @@ def get_notification_ids(self, channels):
151151

152152
def create_alert(self, name, description, severity, for_atleast_s, condition, segmentby=[],
153153
segment_condition='ANY', user_filter='', notify=None, enabled=True, annotations={}):
154+
'''**Description**
155+
Create a threshold-based alert.
156+
157+
**Arguments**
158+
- **name**: the alert name. This will appear in the Sysdig Cloud UI and in notification emails.
159+
- **description**: the alert description. This will appear in the Sysdig Cloud UI and in notification emails.
160+
- **severity**: syslog-encoded alert severity. This is a number from 0 to 7 where 0 means 'emergency' and 7 is 'debug'.
161+
- **for_atleast_s**: the number of consecutive seconds the condition must be satisfied for the alert to fire.
162+
- **condition**: the alert condition, as described here https://app.sysdigcloud.com/apidocs/#!/Alerts/post_api_alerts
163+
- **segmentby**: a list of Sysdig Cloud segmentation criteria that can be used to apply the alert to multiple entities. For example, segmenting a CPU alert by ['host.mac', 'proc.name'] allows to apply it to any process in any machine.
164+
- **segment_condition**: When *segmentby* is specified (and therefore the alert will cover multiple entities) this field is used to determine when it will fire. In particular, you have two options for *segment_condition*: **ANY** (the alert will fire when at least one of the monitored entities satisfies the condition) and **ALL** (the alert will fire when all of the monitored entities satisfy the condition).
165+
- **user_filter**: a boolean expression combining Sysdig Cloud segmentation criteria that makes it possible to reduce the scope of the alert. For example: *kubernetes.namespace.name='production' and container.image='nginx'*.
166+
- **notify**: the type of notification you want this alert to generate. Options are *EMAIL*, *SNS*, *PAGER_DUTY*, *SYSDIG_DUMP*.
167+
- **enabled**: if True, the alert will be enabled when created.
168+
- **annotations**: an optional dictionary of custom properties that you can associate to this alert for automation or management reasons
169+
170+
**Success Return Value**
171+
A dictionary describing the just created alert, with the format described at `this link <https://app.sysdigcloud.com/apidocs/#!/Alerts/post_api_alerts>`_
172+
173+
**Example**
174+
`examples/create_alert.py <https://github.com/draios/python-sdc-client/blob/master/examples/create_alert.py>`_
175+
'''
154176
#
155177
# Get the list of alerts from the server
156178
#
@@ -437,6 +459,19 @@ def create_dashboard_with_configuration(self, configuration):
437459
return [True, res.json()]
438460

439461
def create_dashboard(self, name):
462+
'''
463+
**Description**
464+
Creates an empty dashboard. You can then add panels by using ``add_dashboard_panel``.
465+
466+
**Arguments**
467+
- **name**: the name of the dashboard that will be created.
468+
469+
**Success Return Value**
470+
A dictionary showing the details of the new dashboard.
471+
472+
**Example**
473+
`examples/dashboard.py <https://github.com/draios/python-sdc-client/blob/master/examples/dashboard.py>`_
474+
'''
440475
dashboard_configuration = {
441476
'name': name,
442477
'schema': 1,
@@ -453,6 +488,28 @@ def create_dashboard(self, name):
453488
return [True, res.json()]
454489

455490
def add_dashboard_panel(self, dashboard, name, panel_type, metrics, scope=None, sort_by=None, limit=None, layout=None):
491+
"""**Description**
492+
Adds a panel to the dashboard. A panel can be a time series, or a top chart (i.e. bar chart), or a number panel.
493+
494+
**Arguments**
495+
- **dashboard**: dashboard to edit
496+
- **name**: name of the new panel
497+
- **panel_type**: type of the new panel. Valid values are: ``timeSeries``, ``top``, ``number``
498+
- **metrics**: a list of dictionaries, specifying the metrics to show in the panel, and optionally, if there is only one metric, a grouping key to segment that metric by. A metric is any of the entries that can be found in the *Metrics* section of the Explore page in Sysdig Cloud. Metric entries require an *aggregations* section specifying how to aggregate the metric across time and groups of containers/hosts. A grouping key is any of the entries that can be found in the *Show* or *Segment By* sections of the Explore page in Sysdig Cloud. Refer to the examples section below for ready to use code snippets. Note, certain panels allow certain combinations of metrics and grouping keys:
499+
- ``timeSeries``: 1 or more metrics OR 1 metric + 1 grouping key
500+
- ``top``: 1 or more metrics OR 1 metric + 1 grouping key
501+
- ``number``: 1 metric only
502+
- **scope**: filter to apply to the panel; must be based on metadata available in Sysdig Cloud; Example: *kubernetes.namespace.name='production' and container.image='nginx'*.
503+
- **sort_by**: Data sorting; The parameter is optional and it's a dictionary of ``metric`` and ``mode`` (it can be ``desc`` or ``asc``)
504+
- **limit**: This parameter sets the limit on the number of lines/bars shown in a ``timeSeries`` or ``top`` panel. In the case of more entities being available than the limit, the top entities according to the sort will be shown. The default value is 10 for ``top`` panels (for ``timeSeries`` the default is defined by Sysdig Cloud itself). Note that increasing the limit above 10 is not officially supported and may cause performance and rendering issues
505+
- **layout**: Size and position of the panel. The dashboard layout is defined by a grid of 12 columns, each row height is equal to the column height. For example, say you want to show 2 panels at the top: one panel might be 6 x 3 (half the width, 3 rows height) located in row 1 and column 1 (top-left corner of the viewport), the second panel might be 6 x 3 located in row 1 and position 7. The location is specified by a dictionary of ``row`` (row position), ``col`` (column position), ``size_x`` (width), ``size_y`` (height).
506+
507+
**Success Return Value**
508+
A dictionary showing the details of the edited dashboard.
509+
510+
**Example**
511+
`examples/dashboard.py <https://github.com/draios/python-sdc-client/blob/master/examples/dashboard.py>`_
512+
"""
456513
panel_configuration = {
457514
'name': name,
458515
'showAs': None,
@@ -745,6 +802,22 @@ def create_dashboard_from_view(self, newdashname, viewname, filter, shared=False
745802
return self.create_dashboard_from_template(newdashname, view, filter, shared, annotations)
746803

747804
def create_dashboard_from_dashboard(self, newdashname, templatename, filter, shared=False, annotations={}):
805+
'''**Description**
806+
Create a new dasboard using one of the existing dashboards as a template. You will be able to define the scope of the new dasboard.
807+
808+
**Arguments**
809+
- **newdashname**: the name of the dashboard that will be created.
810+
- **viewname**: the name of the dasboard to use as the template, as it appears in the Sysdig Cloud dashboard page.
811+
- **filter**: a boolean expression combining Sysdig Cloud segmentation criteria defines what the new dasboard will be applied to. For example: *kubernetes.namespace.name='production' and container.image='nginx'*.
812+
- **shared**: if set to True, the new dashboard will be a shared one.
813+
- **annotations**: an optional dictionary of custom properties that you can associate to this dashboard for automation or management reasons
814+
815+
**Success Return Value**
816+
A dictionary showing the details of the new dashboard.
817+
818+
**Example**
819+
`examples/create_dashboard.py <https://github.com/draios/python-sdc-client/blob/master/examples/create_dashboard.py>`_
820+
'''
748821
#
749822
# Get the list of dashboards from the server
750823
#
@@ -774,6 +847,23 @@ def create_dashboard_from_dashboard(self, newdashname, templatename, filter, sha
774847
return self.create_dashboard_from_template(newdashname, dboard, filter, shared, annotations)
775848

776849
def create_dashboard_from_file(self, newdashname, filename, filter, shared=False, annotations={}):
850+
'''
851+
**Description**
852+
Create a new dasboard using a dashboard template saved to disk.
853+
854+
**Arguments**
855+
- **newdashname**: the name of the dashboard that will be created.
856+
- **filename**: name of a file containing a JSON object for a dashboard in the format of an array element returned by :func:`~sdcclient._client.SdcClient.get_dashboards`
857+
- **filter**: a boolean expression combining Sysdig Cloud segmentation criteria defines what the new dasboard will be applied to. For example: *kubernetes.namespace.name='production' and container.image='nginx'*.
858+
- **shared**: if set to True, the new dashboard will be a shared one.
859+
- **annotations**: an optional dictionary of custom properties that you can associate to this dashboard for automation or management reasons
860+
861+
**Success Return Value**
862+
A dictionary showing the details of the new dashboard.
863+
864+
**Example**
865+
`examples/dashboard_save_load.py <https://github.com/draios/python-sdc-client/blob/master/examples/dashboard_save_load.py>`_
866+
'''
777867
#
778868
# Load the Dashboard
779869
#

0 commit comments

Comments
 (0)