Make the ansible-role-ara-api docs prettier
- Add a screenshot at the top - Add in pygments_lexer sphinx extension for yaml+jinja highlight - Improve defaults/main.yaml docs - Do a literal include of defaults/main.yaml in the docs Change-Id: I9fdc1c8dc14f87772b55eb8664ae7a803696450b
This commit is contained in:
David Moreau Simard
parent
f61531ab9a
commit
5edc322d5b
711
doc/source/_extensions/pygments_lexer.py
Normal file
711
doc/source/_extensions/pygments_lexer.py
Normal file
@ -0,0 +1,711 @@
|
||||
# -*- coding: utf-8 -*-
|
||||
# https://github.com/ansible/ansible/blob/6421e89e23524237a2baa352615b15bab2fb7c97/docs/docsite/_extensions/pygments_lexer.py
|
||||
# pylint: disable=no-self-argument
|
||||
#
|
||||
# Copyright 2006-2017 by the Pygments team, see AUTHORS at
|
||||
# https://bitbucket.org/birkenfeld/pygments-main/raw/7941677dc77d4f2bf0bbd6140ade85a9454b8b80/AUTHORS
|
||||
# Copyright by Kirill Simonov (original author of YAML lexer).
|
||||
# Copyright by Norman Richards (original author of JSON lexer).
|
||||
#
|
||||
# Licensed under BSD license:
|
||||
#
|
||||
# Copyright (c) 2006-2017 by the respective authors (see AUTHORS file).
|
||||
# All rights reserved.
|
||||
#
|
||||
# Redistribution and use in source and binary forms, with or without
|
||||
# modification, are permitted provided that the following conditions are
|
||||
# met:
|
||||
#
|
||||
# * Redistributions of source code must retain the above copyright
|
||||
# notice, this list of conditions and the following disclaimer.
|
||||
#
|
||||
# * 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 COPYRIGHT HOLDERS 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 COPYRIGHT
|
||||
# OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
|
||||
# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
|
||||
# LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
|
||||
# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
|
||||
# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
|
||||
# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
|
||||
# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
||||
|
||||
from __future__ import absolute_import, print_function
|
||||
|
||||
from pygments.lexer import LexerContext, ExtendedRegexLexer, DelegatingLexer, RegexLexer, bygroups, include
|
||||
from pygments.lexers import DiffLexer
|
||||
from pygments import token
|
||||
|
||||
import re
|
||||
|
||||
|
||||
class AnsibleYamlLexerContext(LexerContext):
|
||||
"""Indentation context for the YAML lexer."""
|
||||
|
||||
def __init__(self, *args, **kwds):
|
||||
super(AnsibleYamlLexerContext, self).__init__(*args, **kwds)
|
||||
self.indent_stack = []
|
||||
self.indent = -1
|
||||
self.next_indent = 0
|
||||
self.block_scalar_indent = None
|
||||
|
||||
|
||||
class AnsibleYamlLexer(ExtendedRegexLexer):
|
||||
"""
|
||||
Lexer for `YAML <http://yaml.org/>`_, a human-friendly data serialization
|
||||
language.
|
||||
|
||||
.. versionadded:: 0.11
|
||||
"""
|
||||
|
||||
name = 'YAML'
|
||||
aliases = ['yaml']
|
||||
filenames = ['*.yaml', '*.yml']
|
||||
mimetypes = ['text/x-yaml']
|
||||
|
||||
def something(token_class):
|
||||
"""Do not produce empty tokens."""
|
||||
def callback(lexer, match, context):
|
||||
text = match.group()
|
||||
if not text:
|
||||
return
|
||||
yield match.start(), token_class, text
|
||||
context.pos = match.end()
|
||||
return callback
|
||||
|
||||
def reset_indent(token_class):
|
||||
"""Reset the indentation levels."""
|
||||
def callback(lexer, match, context):
|
||||
text = match.group()
|
||||
context.indent_stack = []
|
||||
context.indent = -1
|
||||
context.next_indent = 0
|
||||
context.block_scalar_indent = None
|
||||
yield match.start(), token_class, text
|
||||
context.pos = match.end()
|
||||
return callback
|
||||
|
||||
def save_indent(token_class, start=False):
|
||||
"""Save a possible indentation level."""
|
||||
def callback(lexer, match, context):
|
||||
text = match.group()
|
||||
extra = ''
|
||||
if start:
|
||||
context.next_indent = len(text)
|
||||
if context.next_indent < context.indent:
|
||||
while context.next_indent < context.indent:
|
||||
context.indent = context.indent_stack.pop()
|
||||
if context.next_indent > context.indent:
|
||||
extra = text[context.indent:]
|
||||
text = text[:context.indent]
|
||||
else:
|
||||
context.next_indent += len(text)
|
||||
if text:
|
||||
yield match.start(), token_class, text
|
||||
if extra:
|
||||
yield match.start() + len(text), token_class.Error, extra
|
||||
context.pos = match.end()
|
||||
return callback
|
||||
|
||||
def set_indent(token_class, implicit=False):
|
||||
"""Set the previously saved indentation level."""
|
||||
def callback(lexer, match, context):
|
||||
text = match.group()
|
||||
if context.indent < context.next_indent:
|
||||
context.indent_stack.append(context.indent)
|
||||
context.indent = context.next_indent
|
||||
if not implicit:
|
||||
context.next_indent += len(text)
|
||||
yield match.start(), token_class, text
|
||||
context.pos = match.end()
|
||||
return callback
|
||||
|
||||
def set_block_scalar_indent(token_class):
|
||||
"""Set an explicit indentation level for a block scalar."""
|
||||
def callback(lexer, match, context):
|
||||
text = match.group()
|
||||
context.block_scalar_indent = None
|
||||
if not text:
|
||||
return
|
||||
increment = match.group(1)
|
||||
if increment:
|
||||
current_indent = max(context.indent, 0)
|
||||
increment = int(increment)
|
||||
context.block_scalar_indent = current_indent + increment
|
||||
if text:
|
||||
yield match.start(), token_class, text
|
||||
context.pos = match.end()
|
||||
return callback
|
||||
|
||||
def parse_block_scalar_empty_line(indent_token_class, content_token_class):
|
||||
"""Process an empty line in a block scalar."""
|
||||
def callback(lexer, match, context):
|
||||
text = match.group()
|
||||
if (context.block_scalar_indent is None or
|
||||
len(text) <= context.block_scalar_indent):
|
||||
if text:
|
||||
yield match.start(), indent_token_class, text
|
||||
else:
|
||||
indentation = text[:context.block_scalar_indent]
|
||||
content = text[context.block_scalar_indent:]
|
||||
yield match.start(), indent_token_class, indentation
|
||||
yield (match.start() + context.block_scalar_indent,
|
||||
content_token_class, content)
|
||||
context.pos = match.end()
|
||||
return callback
|
||||
|
||||
def parse_block_scalar_indent(token_class):
|
||||
"""Process indentation spaces in a block scalar."""
|
||||
def callback(lexer, match, context):
|
||||
text = match.group()
|
||||
if context.block_scalar_indent is None:
|
||||
if len(text) <= max(context.indent, 0):
|
||||
context.stack.pop()
|
||||
context.stack.pop()
|
||||
return
|
||||
context.block_scalar_indent = len(text)
|
||||
else:
|
||||
if len(text) < context.block_scalar_indent:
|
||||
context.stack.pop()
|
||||
context.stack.pop()
|
||||
return
|
||||
if text:
|
||||
yield match.start(), token_class, text
|
||||
context.pos = match.end()
|
||||
return callback
|
||||
|
||||
def parse_plain_scalar_indent(token_class):
|
||||
"""Process indentation spaces in a plain scalar."""
|
||||
def callback(lexer, match, context):
|
||||
text = match.group()
|
||||
if len(text) <= context.indent:
|
||||
context.stack.pop()
|
||||
context.stack.pop()
|
||||
return
|
||||
if text:
|
||||
yield match.start(), token_class, text
|
||||
context.pos = match.end()
|
||||
return callback
|
||||
|
||||
tokens = {
|
||||
# the root rules
|
||||
'root': [
|
||||
# ignored whitespaces
|
||||
(r'[ ]+(?=#|$)', token.Text),
|
||||
# line breaks
|
||||
(r'\n+', token.Text),
|
||||
# a comment
|
||||
(r'#[^\n]*', token.Comment.Single),
|
||||
# the '%YAML' directive
|
||||
(r'^%YAML(?=[ ]|$)', reset_indent(token.Name.Tag), 'yaml-directive'),
|
||||
# the %TAG directive
|
||||
(r'^%TAG(?=[ ]|$)', reset_indent(token.Name.Tag), 'tag-directive'),
|
||||
# document start and document end indicators
|
||||
(r'^(?:---|\.\.\.)(?=[ ]|$)', reset_indent(token.Name.Namespace),
|
||||
'block-line'),
|
||||
# indentation spaces
|
||||
(r'[ ]*(?!\s|$)', save_indent(token.Text, start=True),
|
||||
('block-line', 'indentation')),
|
||||
],
|
||||
|
||||
# trailing whitespaces after directives or a block scalar indicator
|
||||
'ignored-line': [
|
||||
# ignored whitespaces
|
||||
(r'[ ]+(?=#|$)', token.Text),
|
||||
# a comment
|
||||
(r'#[^\n]*', token.Comment.Single),
|
||||
# line break
|
||||
(r'\n', token.Text, '#pop:2'),
|
||||
],
|
||||
|
||||
# the %YAML directive
|
||||
'yaml-directive': [
|
||||
# the version number
|
||||
(r'([ ]+)([0-9]+\.[0-9]+)',
|
||||
bygroups(token.Text, token.Number), 'ignored-line'),
|
||||
],
|
||||
|
||||
# the %YAG directive
|
||||
'tag-directive': [
|
||||
# a tag handle and the corresponding prefix
|
||||
(r'([ ]+)(!|![\w-]*!)'
|
||||
r'([ ]+)(!|!?[\w;/?:@&=+$,.!~*\'()\[\]%-]+)',
|
||||
bygroups(token.Text, token.Keyword.Type, token.Text, token.Keyword.Type),
|
||||
'ignored-line'),
|
||||
],
|
||||
|
||||
# block scalar indicators and indentation spaces
|
||||
'indentation': [
|
||||
# trailing whitespaces are ignored
|
||||
(r'[ ]*$', something(token.Text), '#pop:2'),
|
||||
# whitespaces preceeding block collection indicators
|
||||
(r'[ ]+(?=[?:-](?:[ ]|$))', save_indent(token.Text)),
|
||||
# block collection indicators
|
||||
(r'[?:-](?=[ ]|$)', set_indent(token.Punctuation.Indicator)),
|
||||
# the beginning a block line
|
||||
(r'[ ]*', save_indent(token.Text), '#pop'),
|
||||
],
|
||||
|
||||
# an indented line in the block context
|
||||
'block-line': [
|
||||
# the line end
|
||||
(r'[ ]*(?=#|$)', something(token.Text), '#pop'),
|
||||
# whitespaces separating tokens
|
||||
(r'[ ]+', token.Text),
|
||||
# key with colon
|
||||
(r'''([^,:?\[\]{}"'\n]+)(:)(?=[ ]|$)''',
|
||||
bygroups(token.Name.Tag, set_indent(token.Punctuation, implicit=True))),
|
||||
# tags, anchors and aliases,
|
||||
include('descriptors'),
|
||||
# block collections and scalars
|
||||
include('block-nodes'),
|
||||
# flow collections and quoted scalars
|
||||
include('flow-nodes'),
|
||||
# a plain scalar
|
||||
(r'(?=[^\s?:,\[\]{}#&*!|>\'"%@`-]|[?:-]\S)',
|
||||
something(token.Name.Variable),
|
||||
'plain-scalar-in-block-context'),
|
||||
],
|
||||
|
||||
# tags, anchors, aliases
|
||||
'descriptors': [
|
||||
# a full-form tag
|
||||
(r'!<[\w#;/?:@&=+$,.!~*\'()\[\]%-]+>', token.Keyword.Type),
|
||||
# a tag in the form '!', '!suffix' or '!handle!suffix'
|
||||
(r'!(?:[\w-]+!)?'
|
||||
r'[\w#;/?:@&=+$,.!~*\'()\[\]%-]+', token.Keyword.Type),
|
||||
# an anchor
|
||||
(r'&[\w-]+', token.Name.Label),
|
||||
# an alias
|
||||
(r'\*[\w-]+', token.Name.Variable),
|
||||
],
|
||||
|
||||
# block collections and scalars
|
||||
'block-nodes': [
|
||||
# implicit key
|
||||
(r':(?=[ ]|$)', set_indent(token.Punctuation.Indicator, implicit=True)),
|
||||
# literal and folded scalars
|
||||
(r'[|>]', token.Punctuation.Indicator,
|
||||
('block-scalar-content', 'block-scalar-header')),
|
||||
],
|
||||
|
||||
# flow collections and quoted scalars
|
||||
'flow-nodes': [
|
||||
# a flow sequence
|
||||
(r'\[', token.Punctuation.Indicator, 'flow-sequence'),
|
||||
# a flow mapping
|
||||
(r'\{', token.Punctuation.Indicator, 'flow-mapping'),
|
||||
# a single-quoted scalar
|
||||
(r'\'', token.String, 'single-quoted-scalar'),
|
||||
# a double-quoted scalar
|
||||
(r'\"', token.String, 'double-quoted-scalar'),
|
||||
],
|
||||
|
||||
# the content of a flow collection
|
||||
'flow-collection': [
|
||||
# whitespaces
|
||||
(r'[ ]+', token.Text),
|
||||
# line breaks
|
||||
(r'\n+', token.Text),
|
||||
# a comment
|
||||
(r'#[^\n]*', token.Comment.Single),
|
||||
# simple indicators
|
||||
(r'[?:,]', token.Punctuation.Indicator),
|
||||
# tags, anchors and aliases
|
||||
include('descriptors'),
|
||||
# nested collections and quoted scalars
|
||||
include('flow-nodes'),
|
||||
# a plain scalar
|
||||
(r'(?=[^\s?:,\[\]{}#&*!|>\'"%@`])',
|
||||
something(token.Name.Variable),
|
||||
'plain-scalar-in-flow-context'),
|
||||
],
|
||||
|
||||
# a flow sequence indicated by '[' and ']'
|
||||
'flow-sequence': [
|
||||
# include flow collection rules
|
||||
include('flow-collection'),
|
||||
# the closing indicator
|
||||
(r'\]', token.Punctuation.Indicator, '#pop'),
|
||||
],
|
||||
|
||||
# a flow mapping indicated by '{' and '}'
|
||||
'flow-mapping': [
|
||||
# key with colon
|
||||
(r'''([^,:?\[\]{}"'\n]+)(:)(?=[ ]|$)''',
|
||||
bygroups(token.Name.Tag, token.Punctuation)),
|
||||
# include flow collection rules
|
||||
include('flow-collection'),
|
||||
# the closing indicator
|
||||
(r'\}', token.Punctuation.Indicator, '#pop'),
|
||||
],
|
||||
|
||||
# block scalar lines
|
||||
'block-scalar-content': [
|
||||
# line break
|
||||
(r'\n', token.Text),
|
||||
# empty line
|
||||
(r'^[ ]+$',
|
||||
parse_block_scalar_empty_line(token.Text, token.Name.Constant)),
|
||||
# indentation spaces (we may leave the state here)
|
||||
(r'^[ ]*', parse_block_scalar_indent(token.Text)),
|
||||
# line content
|
||||
(r'[\S\t ]+', token.Name.Constant),
|
||||
],
|
||||
|
||||
# the content of a literal or folded scalar
|
||||
'block-scalar-header': [
|
||||
# indentation indicator followed by chomping flag
|
||||
(r'([1-9])?[+-]?(?=[ ]|$)',
|
||||
set_block_scalar_indent(token.Punctuation.Indicator),
|
||||
'ignored-line'),
|
||||
# chomping flag followed by indentation indicator
|
||||
(r'[+-]?([1-9])?(?=[ ]|$)',
|
||||
set_block_scalar_indent(token.Punctuation.Indicator),
|
||||
'ignored-line'),
|
||||
],
|
||||
|
||||
# ignored and regular whitespaces in quoted scalars
|
||||
'quoted-scalar-whitespaces': [
|
||||
# leading and trailing whitespaces are ignored
|
||||
(r'^[ ]+', token.Text),
|
||||
(r'[ ]+$', token.Text),
|
||||
# line breaks are ignored
|
||||
(r'\n+', token.Text),
|
||||
# other whitespaces are a part of the value
|
||||
(r'[ ]+', token.Name.Variable),
|
||||
],
|
||||
|
||||
# single-quoted scalars
|
||||
'single-quoted-scalar': [
|
||||
# include whitespace and line break rules
|
||||
include('quoted-scalar-whitespaces'),
|
||||
# escaping of the quote character
|
||||
(r'\'\'', token.String.Escape),
|
||||
# regular non-whitespace characters
|
||||
(r'[^\s\']+', token.String),
|
||||
# the closing quote
|
||||
(r'\'', token.String, '#pop'),
|
||||
],
|
||||
|
||||
# double-quoted scalars
|
||||
'double-quoted-scalar': [
|
||||
# include whitespace and line break rules
|
||||
include('quoted-scalar-whitespaces'),
|
||||
# escaping of special characters
|
||||
(r'\\[0abt\tn\nvfre "\\N_LP]', token.String),
|
||||
# escape codes
|
||||
(r'\\(?:x[0-9A-Fa-f]{2}|u[0-9A-Fa-f]{4}|U[0-9A-Fa-f]{8})',
|
||||
token.String.Escape),
|
||||
# regular non-whitespace characters
|
||||
(r'[^\s"\\]+', token.String),
|
||||
# the closing quote
|
||||
(r'"', token.String, '#pop'),
|
||||
],
|
||||
|
||||
# the beginning of a new line while scanning a plain scalar
|
||||
'plain-scalar-in-block-context-new-line': [
|
||||
# empty lines
|
||||
(r'^[ ]+$', token.Text),
|
||||
# line breaks
|
||||
(r'\n+', token.Text),
|
||||
# document start and document end indicators
|
||||
(r'^(?=---|\.\.\.)', something(token.Name.Namespace), '#pop:3'),
|
||||
# indentation spaces (we may leave the block line state here)
|
||||
(r'^[ ]*', parse_plain_scalar_indent(token.Text), '#pop'),
|
||||
],
|
||||
|
||||
# a plain scalar in the block context
|
||||
'plain-scalar-in-block-context': [
|
||||
# the scalar ends with the ':' indicator
|
||||
(r'[ ]*(?=:[ ]|:$)', something(token.Text), '#pop'),
|
||||
# the scalar ends with whitespaces followed by a comment
|
||||
(r'[ ]+(?=#)', token.Text, '#pop'),
|
||||
# trailing whitespaces are ignored
|
||||
(r'[ ]+$', token.Text),
|
||||
# line breaks are ignored
|
||||
(r'\n+', token.Text, 'plain-scalar-in-block-context-new-line'),
|
||||
# other whitespaces are a part of the value
|
||||
(r'[ ]+', token.Literal.Scalar.Plain),
|
||||
# regular non-whitespace characters
|
||||
(r'(?::(?!\s)|[^\s:])+', token.Literal.Scalar.Plain),
|
||||
],
|
||||
|
||||
# a plain scalar is the flow context
|
||||
'plain-scalar-in-flow-context': [
|
||||
# the scalar ends with an indicator character
|
||||
(r'[ ]*(?=[,:?\[\]{}])', something(token.Text), '#pop'),
|
||||
# the scalar ends with a comment
|
||||
(r'[ ]+(?=#)', token.Text, '#pop'),
|
||||
# leading and trailing whitespaces are ignored
|
||||
(r'^[ ]+', token.Text),
|
||||
(r'[ ]+$', token.Text),
|
||||
# line breaks are ignored
|
||||
(r'\n+', token.Text),
|
||||
# other whitespaces are a part of the value
|
||||
(r'[ ]+', token.Name.Variable),
|
||||
# regular non-whitespace characters
|
||||
(r'[^\s,:?\[\]{}]+', token.Name.Variable),
|
||||
],
|
||||
|
||||
}
|
||||
|
||||
def get_tokens_unprocessed(self, text=None, context=None):
|
||||
if context is None:
|
||||
context = AnsibleYamlLexerContext(text, 0)
|
||||
return super(AnsibleYamlLexer, self).get_tokens_unprocessed(text, context)
|
||||
|
||||
|
||||
class AnsibleDjangoLexer(RegexLexer):
|
||||
"""
|
||||
Generic `django <http://www.djangoproject.com/documentation/templates/>`_
|
||||
and `jinja <http://wsgiarea.pocoo.org/jinja/>`_ template lexer.
|
||||
|
||||
It just highlights django/jinja code between the preprocessor directives,
|
||||
other data is left untouched by the lexer.
|
||||
"""
|
||||
|
||||
name = 'Django/Jinja'
|
||||
aliases = ['django', 'jinja']
|
||||
mimetypes = ['application/x-django-templating', 'application/x-jinja']
|
||||
|
||||
flags = re.M | re.S
|
||||
|
||||
tokens = {
|
||||
'root': [
|
||||
(r'[^{]+', token.Other),
|
||||
(r'\{\{', token.Comment.Preproc, 'var'),
|
||||
# jinja/django comments
|
||||
(r'\{[*#].*?[*#]\}', token.Comment),
|
||||
# django comments
|
||||
(r'(\{%)(-?\s*)(comment)(\s*-?)(%\})(.*?)'
|
||||
r'(\{%)(-?\s*)(endcomment)(\s*-?)(%\})',
|
||||
bygroups(token.Comment.Preproc, token.Text, token.Keyword, token.Text, token.Comment.Preproc,
|
||||
token.Comment, token.Comment.Preproc, token.Text, token.Keyword, token.Text,
|
||||
token.Comment.Preproc)),
|
||||
# raw jinja blocks
|
||||
(r'(\{%)(-?\s*)(raw)(\s*-?)(%\})(.*?)'
|
||||
r'(\{%)(-?\s*)(endraw)(\s*-?)(%\})',
|
||||
bygroups(token.Comment.Preproc, token.Text, token.Keyword, token.Text, token.Comment.Preproc,
|
||||
token.Text, token.Comment.Preproc, token.Text, token.Keyword, token.Text,
|
||||
token.Comment.Preproc)),
|
||||
# filter blocks
|
||||
(r'(\{%)(-?\s*)(filter)(\s+)([a-zA-Z_]\w*)',
|
||||
bygroups(token.Comment.Preproc, token.Text, token.Keyword, token.Text, token.Name.Function),
|
||||
'block'),
|
||||
(r'(\{%)(-?\s*)([a-zA-Z_]\w*)',
|
||||
bygroups(token.Comment.Preproc, token.Text, token.Keyword), 'block'),
|
||||
(r'\{', token.Other)
|
||||
],
|
||||
'varnames': [
|
||||
(r'(\|)(\s*)([a-zA-Z_]\w*)',
|
||||
bygroups(token.Operator, token.Text, token.Name.Function)),
|
||||
(r'(is)(\s+)(not)?(\s+)?([a-zA-Z_]\w*)',
|
||||
bygroups(token.Keyword, token.Text, token.Keyword, token.Text, token.Name.Function)),
|
||||
(r'(_|true|false|none|True|False|None)\b', token.Keyword.Pseudo),
|
||||
(r'(in|as|reversed|recursive|not|and|or|is|if|else|import|'
|
||||
r'with(?:(?:out)?\s*context)?|scoped|ignore\s+missing)\b',
|
||||
token.Keyword),
|
||||
(r'(loop|block|super|forloop)\b', token.Name.Builtin),
|
||||
(r'[a-zA-Z_][\w-]*', token.Name.Variable),
|
||||
(r'\.\w+', token.Name.Variable),
|
||||
(r':?"(\\\\|\\"|[^"])*"', token.String.Double),
|
||||
(r":?'(\\\\|\\'|[^'])*'", token.String.Single),
|
||||
(r'([{}()\[\]+\-*/%,:~]|[><=]=?|!=)', token.Operator),
|
||||
(r"[0-9](\.[0-9]*)?(eE[+-][0-9])?[flFLdD]?|"
|
||||
r"0[xX][0-9a-fA-F]+[Ll]?", token.Number),
|
||||
],
|
||||
'var': [
|
||||
(r'\s+', token.Text),
|
||||
(r'(-?)(\}\})', bygroups(token.Text, token.Comment.Preproc), '#pop'),
|
||||
include('varnames')
|
||||
],
|
||||
'block': [
|
||||
(r'\s+', token.Text),
|
||||
(r'(-?)(%\})', bygroups(token.Text, token.Comment.Preproc), '#pop'),
|
||||
include('varnames'),
|
||||
(r'.', token.Punctuation)
|
||||
]
|
||||
}
|
||||
|
||||
def analyse_text(text):
|
||||
rv = 0.0
|
||||
if re.search(r'\{%\s*(block|extends)', text) is not None:
|
||||
rv += 0.4
|
||||
if re.search(r'\{%\s*if\s*.*?%\}', text) is not None:
|
||||
rv += 0.1
|
||||
if re.search(r'\{\{.*?\}\}', text) is not None:
|
||||
rv += 0.1
|
||||
return rv
|
||||
|
||||
|
||||
class AnsibleYamlJinjaLexer(DelegatingLexer):
|
||||
"""
|
||||
Subclass of the `DjangoLexer` that highlights unlexed data with the
|
||||
`AnsibleYamlLexer`.
|
||||
|
||||
Commonly used in Saltstack salt states.
|
||||
|
||||
.. versionadded:: 2.0
|
||||
"""
|
||||
|
||||
name = 'YAML+Jinja'
|
||||
aliases = ['yaml+jinja']
|
||||
filenames = ['*.sls']
|
||||
mimetypes = ['text/x-yaml+jinja']
|
||||
|
||||
def __init__(self, **options):
|
||||
super(AnsibleYamlJinjaLexer, self).__init__(AnsibleYamlLexer, AnsibleDjangoLexer, **options)
|
||||
|
||||
|
||||
class AnsibleOutputPrimaryLexer(RegexLexer):
|
||||
name = 'Ansible-output-primary'
|
||||
|
||||
# The following definitions are borrowed from Pygment's JSON lexer.
|
||||
# It has been originally authored by Norman Richards.
|
||||
|
||||
# integer part of a number
|
||||
int_part = r'-?(0|[1-9]\d*)'
|
||||
|
||||
# fractional part of a number
|
||||
frac_part = r'\.\d+'
|
||||
|
||||
# exponential part of a number
|
||||
exp_part = r'[eE](\+|-)?\d+'
|
||||
|
||||
tokens = {
|
||||
# #########################################
|
||||
# # BEGIN: states from JSON lexer #########
|
||||
# #########################################
|
||||
'whitespace': [
|
||||
(r'\s+', token.Text),
|
||||
],
|
||||
|
||||
# represents a simple terminal value
|
||||
'simplevalue': [
|
||||
(r'(true|false|null)\b', token.Keyword.Constant),
|
||||
(('%(int_part)s(%(frac_part)s%(exp_part)s|'
|
||||
'%(exp_part)s|%(frac_part)s)') % vars(),
|
||||
token.Number.Float),
|
||||
(int_part, token.Number.Integer),
|
||||
(r'"(\\\\|\\"|[^"])*"', token.String),
|
||||
],
|
||||
|
||||
|
||||
# the right hand side of an object, after the attribute name
|
||||
'objectattribute': [
|
||||
include('value'),
|
||||
(r':', token.Punctuation),
|
||||
# comma terminates the attribute but expects more
|
||||
(r',', token.Punctuation, '#pop'),
|
||||
# a closing bracket terminates the entire object, so pop twice
|
||||
(r'\}', token.Punctuation, '#pop:2'),
|
||||
],
|
||||
|
||||
# a json object - { attr, attr, ... }
|
||||
'objectvalue': [
|
||||
include('whitespace'),
|
||||
(r'"(\\\\|\\"|[^"])*"', token.Name.Tag, 'objectattribute'),
|
||||
(r'\}', token.Punctuation, '#pop'),
|
||||
],
|
||||
|
||||
# json array - [ value, value, ... }
|
||||
'arrayvalue': [
|
||||
include('whitespace'),
|
||||
include('value'),
|
||||
(r',', token.Punctuation),
|
||||
(r'\]', token.Punctuation, '#pop'),
|
||||
],
|
||||
|
||||
# a json value - either a simple value or a complex value (object or array)
|
||||
'value': [
|
||||
include('whitespace'),
|
||||
include('simplevalue'),
|
||||
(r'\{', token.Punctuation, 'objectvalue'),
|
||||
(r'\[', token.Punctuation, 'arrayvalue'),
|
||||
],
|
||||
# #########################################
|
||||
# # END: states from JSON lexer ###########
|
||||
# #########################################
|
||||
|
||||
'host-postfix': [
|
||||
(r'\n', token.Text, '#pop:3'),
|
||||
(r'( )(=>)( )(\{)',
|
||||
bygroups(token.Text, token.Punctuation, token.Text, token.Punctuation),
|
||||
'objectvalue'),
|
||||
],
|
||||
|
||||
'host-error': [
|
||||
(r'(?:(:)( )(UNREACHABLE|FAILED)(!))?',
|
||||
bygroups(token.Punctuation, token.Text, token.Keyword, token.Punctuation),
|
||||
'host-postfix'),
|
||||
(r'', token.Text, 'host-postfix'),
|
||||
],
|
||||
|
||||
'host-name': [
|
||||
(r'(\[)([^ \]]+)(?:( )(=>)( )([^\]]+))?(\])',
|
||||
bygroups(token.Punctuation, token.Name.Variable, token.Text, token.Punctuation, token.Text, token.Name.Variable, token.Punctuation),
|
||||
'host-error')
|
||||
],
|
||||
|
||||
'host-result': [
|
||||
(r'\n', token.Text, '#pop'),
|
||||
(r'( +)(ok|changed|failed|skipped|unreachable)(=)([0-9]+)',
|
||||
bygroups(token.Text, token.Keyword, token.Punctuation, token.Number.Integer)),
|
||||
],
|
||||
|
||||
'root': [
|
||||
(r'(PLAY|TASK|PLAY RECAP)(?:( )(\[)([^\]]+)(\]))?( )(\*+)(\n)',
|
||||
bygroups(token.Keyword, token.Text, token.Punctuation, token.Literal, token.Punctuation, token.Text, token.Name.Variable, token.Text)),
|
||||
(r'(fatal|ok|changed|skipping)(:)( )',
|
||||
bygroups(token.Keyword, token.Punctuation, token.Text),
|
||||
'host-name'),
|
||||
(r'(\[)(WARNING)(\]:)([^\n]+)',
|
||||
bygroups(token.Punctuation, token.Keyword, token.Punctuation, token.Text)),
|
||||
(r'([^ ]+)( +)(:)',
|
||||
bygroups(token.Name, token.Text, token.Punctuation),
|
||||
'host-result'),
|
||||
(r'(\tto retry, use: )(.*)(\n)', bygroups(token.Text, token.Literal.String, token.Text)),
|
||||
(r'.*\n', token.Other),
|
||||
],
|
||||
}
|
||||
|
||||
|
||||
class AnsibleOutputLexer(DelegatingLexer):
|
||||
name = 'Ansible-output'
|
||||
aliases = ['ansible-output']
|
||||
|
||||
def __init__(self, **options):
|
||||
super(AnsibleOutputLexer, self).__init__(DiffLexer, AnsibleOutputPrimaryLexer, **options)
|
||||
|
||||
|
||||
# ####################################################################################################
|
||||
# # Sphinx plugin ####################################################################################
|
||||
# ####################################################################################################
|
||||
|
||||
__version__ = "0.1.0"
|
||||
__license__ = "BSD license"
|
||||
__author__ = "Felix Fontein"
|
||||
__author_email__ = "felix@fontein.de"
|
||||
|
||||
|
||||
def setup(app):
|
||||
""" Initializer for Sphinx extension API.
|
||||
See http://www.sphinx-doc.org/en/stable/extdev/index.html#dev-extensions.
|
||||
"""
|
||||
for lexer in [
|
||||
AnsibleDjangoLexer(startinline=True),
|
||||
AnsibleYamlLexer(startinline=True),
|
||||
AnsibleYamlJinjaLexer(startinline=True),
|
||||
AnsibleOutputLexer(startinline=True)
|
||||
]:
|
||||
app.add_lexer(lexer.name, lexer)
|
||||
for alias in lexer.aliases:
|
||||
app.add_lexer(alias, lexer)
|
||||
|
||||
return dict(version=__version__, parallel_read_safe=True)
|
||||
BIN
doc/source/_static/ansible-role-ara-api.png
Normal file
BIN
doc/source/_static/ansible-role-ara-api.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 21 KiB |
@ -1 +1,2 @@
|
||||
.. include:: ../../roles/ara_api/README.rst
|
||||
:end-before: include_delimiter_end
|
||||
@ -23,13 +23,15 @@ import pbr.version
|
||||
version_info = pbr.version.VersionInfo('ara')
|
||||
|
||||
sys.path.insert(0, os.path.abspath('../..'))
|
||||
sys.path.append(os.path.abspath('_extensions'))
|
||||
# -- 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',
|
||||
'sphinx.ext.autosectionlabel'
|
||||
'sphinx.ext.autosectionlabel',
|
||||
'pygments_lexer'
|
||||
]
|
||||
|
||||
# autodoc generation is a bit aggressive and a nuisance when doing heavy
|
||||
@ -60,7 +62,7 @@ add_function_parentheses = True
|
||||
add_module_names = True
|
||||
|
||||
# The name of the Pygments (syntax highlighting) style to use.
|
||||
pygments_style = 'sphinx'
|
||||
pygments_style = 'default'
|
||||
|
||||
# -- Options for HTML output --------------------------------------------------
|
||||
|
||||
|
||||
@ -1,9 +1,11 @@
|
||||
ansible-role-ara-api
|
||||
====================
|
||||
|
||||
.. image:: ../../doc/source/_static/ansible-role-ara-api.png
|
||||
|
||||
This Ansible role provides a framework for installing one or many instances of
|
||||
`ara <https://github.com/openstack/ara>`_ in a variety of opinionated
|
||||
deployment topologies.
|
||||
`ARA Records Ansible <https://github.com/openstack/ara>`_ in a variety of
|
||||
opinionated deployment topologies.
|
||||
|
||||
It is currently tested and supported against Ubuntu 18.04 and Fedora 29.
|
||||
|
||||
@ -12,18 +14,22 @@ Role Variables
|
||||
|
||||
See `defaults/main.yaml <https://github.com/openstack/ara/blob/feature/1.0/roles/ara_api/defaults/main.yaml>`_.
|
||||
|
||||
.. literalinclude:: ../../roles/ara_api/defaults/main.yaml
|
||||
:language: yaml+jinja
|
||||
:start-after: www.gnu.org
|
||||
|
||||
TL;DR
|
||||
-----
|
||||
|
||||
Playbook that runs the role with defaults::
|
||||
Playbook that runs the role with defaults:
|
||||
|
||||
# Doesn't require superuser privileges
|
||||
# The API will only be reachable by the offline API client
|
||||
- name: Install ARA with default settings and no persistent API server
|
||||
hosts: all
|
||||
gather_facts: yes
|
||||
roles:
|
||||
- ara_api
|
||||
.. code-block:: yaml+jinja
|
||||
|
||||
- name: Install ARA with default settings and no persistent API server
|
||||
hosts: all
|
||||
gather_facts: yes
|
||||
roles:
|
||||
- ara_api
|
||||
|
||||
What the role ends up doing by default:
|
||||
|
||||
@ -61,26 +67,28 @@ Or any combination of any of those.
|
||||
Example playbooks
|
||||
-----------------
|
||||
|
||||
Install ARA and set up the API to be served by a persistent gunicorn service::
|
||||
Install ARA and set up the API to be served by a persistent gunicorn service:
|
||||
|
||||
# Requires superuser privileges to set up the ara-api service
|
||||
# The API will be reachable at http://127.0.0.1:8000/api/v1/
|
||||
- name: Install ARA and set up the API to be served by gunicorn
|
||||
hosts: all
|
||||
gather_facts: yes
|
||||
vars:
|
||||
ara_api_wsgi_server: gunicorn
|
||||
roles:
|
||||
- ara_api
|
||||
.. code-block:: yaml+jinja
|
||||
|
||||
Install ARA and set up the API to be served by nginx in front of gunicorn::
|
||||
- name: Install ARA and set up the API to be served by gunicorn
|
||||
hosts: all
|
||||
gather_facts: yes
|
||||
vars:
|
||||
ara_api_wsgi_server: gunicorn
|
||||
roles:
|
||||
- ara_api
|
||||
|
||||
# Requires superuser privileges to set up nginx and the ara-api service
|
||||
# The API will be reachable at http://api.ara.example.org
|
||||
- name: Install ARA and set up the API to be served by nginx in front of gunicorn
|
||||
hosts: all
|
||||
gather_facts: yes
|
||||
vars:
|
||||
Install ARA and set up the API to be served by nginx in front of gunicorn:
|
||||
|
||||
.. code-block:: yaml+jinja
|
||||
|
||||
# Requires superuser privileges to set up nginx and the ara-api service
|
||||
# The API will be reachable at http://api.ara.example.org
|
||||
- name: Install ARA and set up the API to be served by nginx in front of gunicorn
|
||||
hosts: all
|
||||
gather_facts: yes
|
||||
vars:
|
||||
ara_api_frontend_server: nginx
|
||||
ara_api_wsgi_server: gunicorn
|
||||
ara_api_fqdn: api.ara.example.org
|
||||
@ -90,22 +98,24 @@ Install ARA and set up the API to be served by nginx in front of gunicorn::
|
||||
roles:
|
||||
- ara_api
|
||||
|
||||
.. _include_delimiter_end:
|
||||
|
||||
Copyright
|
||||
---------
|
||||
|
||||
::
|
||||
.. code-block:: text
|
||||
|
||||
Copyright (c) 2019 Red Hat, Inc.
|
||||
Copyright (c) 2019 Red Hat, Inc.
|
||||
|
||||
ARA Records Ansible is free software: you can redistribute it and/or modify
|
||||
it under the terms of the GNU General Public License as published by
|
||||
the Free Software Foundation, either version 3 of the License, or
|
||||
(at your option) any later version.
|
||||
ARA Records Ansible is free software: you can redistribute it and/or modify
|
||||
it under the terms of the GNU General Public License as published by
|
||||
the Free Software Foundation, either version 3 of the License, or
|
||||
(at your option) any later version.
|
||||
|
||||
ARA Records Ansible is distributed in the hope that it will be useful,
|
||||
but WITHOUT ANY WARRANTY; without even the implied warranty of
|
||||
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
||||
GNU General Public License for more details.
|
||||
ARA Records Ansible is distributed in the hope that it will be useful,
|
||||
but WITHOUT ANY WARRANTY; without even the implied warranty of
|
||||
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
||||
GNU General Public License for more details.
|
||||
|
||||
You should have received a copy of the GNU General Public License
|
||||
along with ARA Records Ansible. If not, see <http://www.gnu.org/licenses/>.
|
||||
You should have received a copy of the GNU General Public License
|
||||
along with ARA Records Ansible. If not, see <http://www.gnu.org/licenses/>.
|
||||
|
||||
@ -16,54 +16,56 @@
|
||||
# You should have received a copy of the GNU General Public License
|
||||
# along with ARA Records Ansible. If not, see <http://www.gnu.org/licenses/>.
|
||||
|
||||
# Root directories in which data, configuration and logs will be stored
|
||||
ara_api_root_dir: "{{ ansible_user_dir }}/.ara" # git repos, virtualenvs, sqlite db
|
||||
ara_api_log_dir: "{{ ara_api_root_dir }}/logs" # logs
|
||||
# Root directory where every file for the ARA installation are located
|
||||
ara_api_root_dir: "{{ ansible_user_dir }}/.ara"
|
||||
|
||||
# Directory where logs are written to
|
||||
ara_api_log_dir: "{{ ara_api_root_dir }}/logs"
|
||||
|
||||
# Whether or not ara should be installed in a virtual environment.
|
||||
# Running ara in a virtualenv is recommended to avoid conflicting with
|
||||
# system-wide python packages.
|
||||
# This defaults to true to prevent conflicting with system or distribution
|
||||
# python packages.
|
||||
ara_api_venv: true
|
||||
|
||||
# When using a virtualenv, location where it will be installed
|
||||
# When using a virtualenv, path to where it will be installed
|
||||
ara_api_venv_path: "{{ ara_api_root_dir }}/virtualenv"
|
||||
|
||||
# How ara will be installed
|
||||
# source (default): installs from a local or remote git repository specified by ara_api_source
|
||||
# pypi (planned): installs from pypi
|
||||
# How ARA will be installed
|
||||
# - source [default]: installs from a local or remote git repository
|
||||
# - pypi [planned]: installs from pypi
|
||||
ara_api_install_method: source
|
||||
|
||||
# The source where the git repository can be cloned from.
|
||||
# Can be an URL to a git repository or the path to a local repository on disk.
|
||||
# When installing from source, the URL or filesystem path where the git source
|
||||
# repository can be cloned from.
|
||||
ara_api_source: "https://git.openstack.org/openstack/ara"
|
||||
|
||||
# Location where ara will be checked out when installing from source
|
||||
# When installing from source, location where the source repository will be checked out to.
|
||||
ara_api_source_checkout: "{{ ara_api_root_dir }}/git/ara"
|
||||
|
||||
# Version of ara to install
|
||||
# This can be a git ref (tag, branch, commit) when installing from source or
|
||||
# it can be a version number released to PyPi.
|
||||
# Version of ARA to install
|
||||
# When installing from source, this can be a git ref (tag, branch, commit, etc)
|
||||
# When installing from PyPi, it would be a version number that has been released.
|
||||
# When using "latest" as the source version, HEAD will be used
|
||||
# When using "latest" as the pypi version, the latest release will be used
|
||||
ara_api_version: feature/1.0
|
||||
|
||||
# The frontend/web server for serving the ARA API
|
||||
# It is recommended to specify a web server when deploying a production environment.
|
||||
# API browser.
|
||||
# - none (null - default)
|
||||
# - nginx (recommended)
|
||||
# - apache (planned)
|
||||
# - null [default]: No frontend server will be set up.
|
||||
# - nginx: Nginx will be configured in front of the WSGI application server.
|
||||
# - apache [planned]
|
||||
ara_api_frontend_server: null
|
||||
|
||||
# When using a frontend server, you can override the default vhost configuration
|
||||
# template by specifying the path to your own template file.
|
||||
# Path to a custom vhost configuration jinja template
|
||||
# The vhost configuration templates provided by the role are simple by design
|
||||
# and are not sufficient to cover every use cases.
|
||||
# Use this variable if you need to have your own custom nginx or apache configuration.
|
||||
ara_api_frontend_vhost: null
|
||||
|
||||
# The WSGI server for running ARA's API server
|
||||
# - none (null - default)
|
||||
# - gunicorn (recommended)
|
||||
# - uwsgi (planned)
|
||||
# - mod_wsgi (planned)
|
||||
# - null [default]: No persistent WSGI application server will be set up. Only the offline API client will work.
|
||||
# - gunicorn: gunicorn will be installed and set up to run the API as a systemd service.
|
||||
# - mod_wsgi [planned]
|
||||
ara_api_wsgi_server: null
|
||||
|
||||
# Address and port on which the wsgi server will bind
|
||||
@ -71,7 +73,7 @@ ara_api_wsgi_server: null
|
||||
# "ara_api_cors_origin_whitelist".
|
||||
ara_api_wsgi_bind: "127.0.0.1:8000"
|
||||
|
||||
# When using a web server, the domain it will be listening on
|
||||
# When using a frontend server, the domain it will be listening on
|
||||
ara_api_fqdn: "{{ ansible_default_ipv4['address'] }}"
|
||||
|
||||
####################################
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user