Slide 1

Slide 1 text

OpenStack + Sphinx In A Tree Stephen Finucane (@stephenfin) 2017-11-06, OpenStack Summit Sydney

Slide 2

Slide 2 text

Intro What’s a Directive? .. directive_name:: [arg [arg...]] :option: [option_arg] Body text here.

Slide 3

Slide 3 text

Intro What can OpenStack offer? ● oslo.config ● oslo.policy ● cliff ● stevedore

Slide 4

Slide 4 text

oslo.config Two extensions ● A config documentation directive and role ● A config generator hook

Slide 5

Slide 5 text

oslo.config Directive and Role .. show-options:: oslo.config oslo.log :oslo.config:option:`config_file`

Slide 6

Slide 6 text

https://docs.openstack.org/nova/pike/configuration/config.html

Slide 7

Slide 7 text

oslo.config Config Generator config_generator_config_file = [ ('../../etc/glance-api.conf', 'api'), ('../../etc/glance-cache.conf', 'cache'), ('../../etc/glance-glare.conf', None), ('../../etc/glance-registry.conf', None), ('../../etc/glance-scrubber.conf', None), ]

Slide 8

Slide 8 text

https://docs.openstack.org/nova/pike/configuration/sample-config.html

Slide 9

Slide 9 text

oslo.policy Also has two extensions ● A policy documentation directive ● A policy generator hook

Slide 10

Slide 10 text

oslo.policy Directive .. show-policy:: :config-file: etc/nova/nova-policy-generator.conf

Slide 11

Slide 11 text

https://docs.openstack.org/nova/pike/configuration/policy.html

Slide 12

Slide 12 text

oslo.policy Config Generator policy_generator_config_file = '../../etc/nova/nova-policy-generator.conf' sample_policy_basename = '_static/nova'

Slide 13

Slide 13 text

https://docs.openstack.org/nova/pike/configuration/sample-policy.html

Slide 14

Slide 14 text

cliff One directive that handles multiple commands Uses standard domain directives; program, option, envvar

Slide 15

Slide 15 text

cliff Directive .. autoprogram-cliff:: openstack.compute.v2 :command: server add fixed ip :prog:`openstack server add fixed ip`

Slide 16

Slide 16 text

https://docs.openstack.org/python-openstackclient/latest/cli/command-objects/access-token.html

Slide 17

Slide 17 text

Stevedore A single directive for listing plugins for an entrypoint

Slide 18

Slide 18 text

Stevedore Directive .. list-plugins:: stevedore.example.formatter

Slide 19

Slide 19 text

https://docs.openstack.org/oslo.messaging/latest/admin/drivers.html

Slide 20

Slide 20 text

Wrap Up Links & Resources ● oslo.config Directive ● oslo.config Configuration Generator ● oslo.policy Directive ● oslo.policy Configuration Generator ● cliff Directive ● stevedore Directive