def test_group_obj_with_help(self):
# option with None group placed in DEFAULT
results = "\n".join(
list(
sphinxext._format_group(
app=mock.Mock(),
namespace=None,
group_name="group",
group_obj=cfg.OptGroup("group", help="group help"),
opt_list=[cfg.StrOpt("opt_name")],
)
)
)
self.assertEqual(
textwrap.dedent(
"""
.. oslo.config:group:: group
group help
.. oslo.config:option:: opt_name
:Type: string
:Default: ``<None>``
"""
).lstrip(),
results,
)
def test_with_default_value(self):
results = '\n'.join(
list(
sphinxext._format_group(
app=mock.Mock(),
namespace=None,
group_name=None,
group_obj=None,
opt_list=[
cfg.StrOpt('opt_name',
default='this is the default',
help='this appears in the default group'),
],
)))
self.assertEqual(
textwrap.dedent('''
.. oslo.config:group:: DEFAULT
.. oslo.config:option:: opt_name
:Type: string
:Default: ``this is the default``
this appears in the default group
''').lstrip(), results)
def test_advanced(self):
results = "\n".join(
list(
sphinxext._format_group(
app=mock.Mock(),
namespace=None,
group_name=None,
group_obj=None,
opt_list=[cfg.StrOpt("opt_name", advanced=True)],
)
)
)
self.assertEqual(
textwrap.dedent(
"""
.. oslo.config:group:: DEFAULT
.. oslo.config:option:: opt_name
:Type: string
:Default: ``<None>``
:Advanced Option: intended for advanced users and not used
:by the majority of users, and might have a significant
:effect on stability and/or performance.
"""
).lstrip(),
results,
)
def test_not_advanced(self):
results = "\n".join(
list(
sphinxext._format_group(
app=mock.Mock(),
namespace=None,
group_name=None,
group_obj=None,
opt_list=[cfg.StrOpt("opt_name", advanced=False)],
)
)
)
self.assertEqual(
textwrap.dedent(
"""
.. oslo.config:group:: DEFAULT
.. oslo.config:option:: opt_name
:Type: string
:Default: ``<None>``
"""
).lstrip(),
results,
)
def test_with_choices(self):
results = "\n".join(
list(
sphinxext._format_group(
app=mock.Mock(),
namespace=None,
group_name=None,
group_obj=None,
opt_list=[cfg.StrOpt("opt_name", choices=["a", "b", "c", None, ""])],
)
)
)
self.assertEqual(
textwrap.dedent(
"""
.. oslo.config:group:: DEFAULT
.. oslo.config:option:: opt_name
:Type: string
:Default: ``<None>``
:Valid Values: a, b, c, <None>, ''
"""
).lstrip(),
results,
)
def test_deprecated_opts(self):
results = '\n'.join(list(sphinxext._format_group(
app=mock.Mock(),
namespace=None,
group_name=None,
group_obj=None,
opt_list=[
cfg.StrOpt('opt_name',
deprecated_name='deprecated_name',
)
],
)))
self.assertEqual(textwrap.dedent('''
.. oslo.config:group:: DEFAULT
.. oslo.config:option:: opt_name
:Type: string
:Default: ``<None>``
.. list-table:: Deprecated Variations
:header-rows: 1
- * Group
* Name
- * DEFAULT
* deprecated_name
''').lstrip(), results)
def test_with_default_value(self):
results = "\n".join(
list(
sphinxext._format_group(
app=mock.Mock(),
namespace=None,
group_name=None,
group_obj=None,
opt_list=[
cfg.StrOpt("opt_name", default="this is the default", help="this appears in the default group")
],
)
)
)
self.assertEqual(
textwrap.dedent(
"""
.. oslo.config:group:: DEFAULT
.. oslo.config:option:: opt_name
:Type: string
:Default: ``this is the default``
this appears in the default group
"""
).lstrip(),
results,
)
def test_with_min(self):
results = "\n".join(
list(
sphinxext._format_group(
app=mock.Mock(),
namespace=None,
group_name=None,
group_obj=None,
opt_list=[cfg.IntOpt("opt_name", min=1)],
)
)
)
self.assertEqual(
textwrap.dedent(
"""
.. oslo.config:group:: DEFAULT
.. oslo.config:option:: opt_name
:Type: integer
:Default: ``<None>``
:Minimum Value: 1
"""
).lstrip(),
results,
)
def test_deprecated_opts_with_deprecated_group(self):
results = '\n'.join(
list(
sphinxext._format_group(
app=mock.Mock(),
namespace=None,
group_name=None,
group_obj=None,
opt_list=[
cfg.StrOpt(
'opt_name',
deprecated_name='deprecated_name',
deprecated_group='deprecated_group',
)
],
)))
self.assertEqual(
textwrap.dedent('''
.. oslo.config:group:: DEFAULT
.. oslo.config:option:: opt_name
:Type: string
:Default: ``<None>``
.. list-table:: Deprecated Variations
:header-rows: 1
- * Group
* Name
- * deprecated_group
* deprecated_name
''').lstrip(), results)
def test_mutable(self):
results = "\n".join(
list(
sphinxext._format_group(
app=mock.Mock(),
namespace=None,
group_name=None,
group_obj=None,
opt_list=[cfg.IntOpt("opt_name", mutable=True)],
)
)
)
self.assertEqual(
textwrap.dedent(
"""
.. oslo.config:group:: DEFAULT
.. oslo.config:option:: opt_name
:Type: integer
:Default: ``<None>``
:Mutable: This option can be changed without restarting.
"""
).lstrip(),
results,
)
def test_advanced(self):
results = '\n'.join(
list(
sphinxext._format_group(
app=mock.Mock(),
namespace=None,
group_name=None,
group_obj=None,
opt_list=[
cfg.StrOpt('opt_name', advanced=True),
],
)))
self.assertEqual(
textwrap.dedent('''
.. oslo.config:group:: DEFAULT
.. oslo.config:option:: opt_name
:Type: string
:Default: ``<None>``
:Advanced Option: intended for advanced users and not used
:by the majority of users, and might have a significant
:effect on stability and/or performance.
''').lstrip(), results)
def test_deprecated_for_removal(self):
results = '\n'.join(list(sphinxext._format_group(
app=mock.Mock(),
namespace=None,
group_name=None,
group_obj=None,
opt_list=[
cfg.StrOpt('opt_name',
deprecated_for_removal=True,
deprecated_reason='because I said so',
)
],
)))
self.assertIn('.. warning::', results)
self.assertIn('because I said so', results)
def test_deprecated_for_removal(self):
results = '\n'.join(list(sphinxext._format_group(
app=mock.Mock(),
namespace=None,
group_name=None,
group_obj=None,
opt_list=[
cfg.StrOpt('opt_name',
deprecated_for_removal=True,
deprecated_reason='because I said so',
deprecated_since='13.0',
)
],
)))
self.assertIn('.. warning::', results)
self.assertIn('because I said so', results)
self.assertIn('since 13.0', results)
def test_group_obj_without_help(self):
# option with None group placed in DEFAULT
results = '\n'.join(list(sphinxext._format_group(
app=mock.Mock(),
namespace=None,
group_name='group',
group_obj=cfg.OptGroup('group'),
opt_list=[cfg.StrOpt('opt_name')],
)))
self.assertEqual(textwrap.dedent('''
.. oslo.config:group:: group
.. oslo.config:option:: opt_name
:Type: string
:Default: ``<None>``
''').lstrip(), results)
def test_with_choices_with_descriptions(self):
results = '\n'.join(
list(
sphinxext._format_group(
app=mock.Mock(),
namespace=None,
group_name=None,
group_obj=None,
opt_list=[
cfg.StrOpt('opt_name',
choices=[
('a', 'a is the best'),
('b', 'Actually, may-b I am better'),
('c', 'c, I am clearly the greatest'),
(None, 'I am having none of this'),
('', '')
]),
],
)))
self.assertEqual(
textwrap.dedent('''
.. oslo.config:group:: DEFAULT
.. oslo.config:option:: opt_name
:Type: string
:Default: ``<None>``
:Valid Values: a, b, c, <None>, ''
.. rubric:: Possible values
a
a is the best
b
Actually, may-b I am better
c
c, I am clearly the greatest
<None>
I am having none of this
''
<No description provided>
''').lstrip(), results)
def test_group_obj_without_help(self):
# option with None group placed in DEFAULT
results = '\n'.join(list(sphinxext._format_group(
app=mock.Mock(),
namespace=None,
group_name='group',
group_obj=cfg.OptGroup('group'),
opt_list=[cfg.StrOpt('opt_name')],
)))
self.assertEqual(textwrap.dedent('''
.. oslo.config:group:: group
.. oslo.config:option:: opt_name
:Type: string
:Default: ``<None>``
''').lstrip(), results)
def test_with_choices_with_descriptions(self):
results = '\n'.join(list(sphinxext._format_group(
app=mock.Mock(),
namespace=None,
group_name=None,
group_obj=None,
opt_list=[
cfg.StrOpt(
'opt_name',
choices=[
('a', 'a is the best'),
('b', 'Actually, may-b I am better'),
('c', 'c, I am clearly the greatest'),
(None, 'I am having none of this'),
('', '')]),
],
)))
self.assertEqual(textwrap.dedent('''
.. oslo.config:group:: DEFAULT
.. oslo.config:option:: opt_name
:Type: string
:Default: ``<None>``
:Valid Values: a, b, c, <None>, ''
.. rubric:: Possible values
a
a is the best
b
Actually, may-b I am better
c
c, I am clearly the greatest
<None>
I am having none of this
''
<No description provided>
''').lstrip(), results)
def test_not_mutable(self):
results = '\n'.join(list(sphinxext._format_group(
app=mock.Mock(),
namespace=None,
group_name=None,
group_obj=None,
opt_list=[
cfg.IntOpt('opt_name',
mutable=False),
],
)))
self.assertEqual(textwrap.dedent('''
.. oslo.config:group:: DEFAULT
.. oslo.config:option:: opt_name
:Type: integer
:Default: ``<None>``
''').lstrip(), results)
def test_not_advanced(self):
results = '\n'.join(list(sphinxext._format_group(
app=mock.Mock(),
namespace=None,
group_name=None,
group_obj=None,
opt_list=[
cfg.StrOpt('opt_name',
advanced=False),
],
)))
self.assertEqual(textwrap.dedent('''
.. oslo.config:group:: DEFAULT
.. oslo.config:option:: opt_name
:Type: string
:Default: ``<None>``
''').lstrip(), results)
def test_with_choices(self):
results = '\n'.join(list(sphinxext._format_group(
app=mock.Mock(),
namespace=None,
group_name=None,
group_obj=None,
opt_list=[
cfg.StrOpt('opt_name',
choices=['a', 'b', 'c', None, '']),
],
)))
self.assertEqual(textwrap.dedent('''
.. oslo.config:group:: DEFAULT
.. oslo.config:option:: opt_name
:Type: string
:Default: ``<None>``
:Valid Values: a, b, c, <None>, ''
''').lstrip(), results)
def test_mutable(self):
results = '\n'.join(list(sphinxext._format_group(
app=mock.Mock(),
namespace=None,
group_name=None,
group_obj=None,
opt_list=[
cfg.IntOpt('opt_name',
mutable=True),
],
)))
self.assertEqual(textwrap.dedent('''
.. oslo.config:group:: DEFAULT
.. oslo.config:option:: opt_name
:Type: integer
:Default: ``<None>``
:Mutable: This option can be changed without restarting.
''').lstrip(), results)
def test_with_min_0(self):
results = '\n'.join(list(sphinxext._format_group(
app=mock.Mock(),
namespace=None,
group_name=None,
group_obj=None,
opt_list=[
cfg.IntOpt('opt_name',
min=0),
],
)))
self.assertEqual(textwrap.dedent('''
.. oslo.config:group:: DEFAULT
.. oslo.config:option:: opt_name
:Type: integer
:Default: ``<None>``
:Minimum Value: 0
''').lstrip(), results)
def test_with_choices(self):
results = '\n'.join(list(sphinxext._format_group(
app=mock.Mock(),
namespace=None,
group_name=None,
group_obj=None,
opt_list=[
cfg.StrOpt('opt_name',
choices=['a', 'b', 'c', None, '']),
],
)))
self.assertEqual(textwrap.dedent('''
.. oslo.config:group:: DEFAULT
.. oslo.config:option:: opt_name
:Type: string
:Default: ``<None>``
:Valid Values: a, b, c, <None>, ''
''').lstrip(), results)
def test_with_default_value(self):
results = '\n'.join(list(sphinxext._format_group(
app=mock.Mock(),
namespace=None,
group_name=None,
group_obj=None,
opt_list=[
cfg.StrOpt('opt_name',
default='this is the default',
help='this appears in the default group'),
],
)))
self.assertEqual(textwrap.dedent('''
.. oslo.config:group:: DEFAULT
.. oslo.config:option:: opt_name
:Type: string
:Default: ``this is the default``
this appears in the default group
''').lstrip(), results)
def test_deprecated_for_removal(self):
results = "\n".join(
list(
sphinxext._format_group(
app=mock.Mock(),
namespace=None,
group_name=None,
group_obj=None,
opt_list=[
cfg.StrOpt(
"opt_name",
deprecated_for_removal=True,
deprecated_reason="because I said so",
deprecated_since="13.0",
)
],
)
)
)
self.assertIn(".. warning::", results)
self.assertIn("because I said so", results)
self.assertIn("since 13.0", results)
def test_deprecated_opts_with_deprecated_group(self):
results = "\n".join(
list(
sphinxext._format_group(
app=mock.Mock(),
namespace=None,
group_name=None,
group_obj=None,
opt_list=[
cfg.StrOpt("opt_name", deprecated_name="deprecated_name", deprecated_group="deprecated_group")
],
)
)
)
self.assertEqual(
textwrap.dedent(
"""
.. oslo.config:group:: DEFAULT
.. oslo.config:option:: opt_name
:Type: string
:Default: ``<None>``
.. list-table:: Deprecated Variations
:header-rows: 1
- * Group
* Name
- * deprecated_group
* deprecated_name
"""
).lstrip(),
results,
)
