OpenStack + Sphinx In A Tree

An overview of the various Sphinx extensions available within the OpenStack ecosystem.

1. OpenStack + Sphinx In A Tree Stephen Finucane (@stephenfin) 2017-11-06, OpenStack Summit Sydney
2. Intro What’s a Directive? .. directive_name:: [arg [arg...]] :option: [option_arg] Body text here.
3. Intro What can OpenStack offer? • oslo.config • oslo.policy • cliff • stevedore
4. oslo.config Two extensions • A config documentation directive and role • A config generator hook
5. oslo.config Directive and Role .. show-options:: oslo.config oslo.log :oslo.config:option:`config_file`
6. https://docs.openstack.org/nova/pike/configuration/config.html
7. 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), ]
8. https://docs.openstack.org/nova/pike/configuration/sample-config.html
9. oslo.policy Also has two extensions • A policy documentation directive • A policy generator hook
10. oslo.policy Directive .. show-policy:: :config-file: etc/nova/nova-policy-generator.conf
11. https://docs.openstack.org/nova/pike/configuration/policy.html
12. oslo.policy Config Generator policy_generator_config_file = '../../etc/nova/nova-policy-generator.conf' sample_policy_basename = '_static/nova'
13. https://docs.openstack.org/nova/pike/configuration/sample-policy.html
14. cliff One directive that handles multiple commands Uses standard domain directives; program, option, envvar
15. cliff Directive .. autoprogram-cliff:: openstack.compute.v2 :command: server add fixed ip :prog:`openstack server add fixed ip`
16. https://docs.openstack.org/python-openstackclient/latest/cli/command-objects/access-token.html
17. Stevedore A single directive for listing plugins for an entrypoint
18. Stevedore Directive .. list-plugins:: stevedore.example.formatter
19. https://docs.openstack.org/oslo.messaging/latest/admin/drivers.html
20. Wrap Up Links & Resources • oslo.config Directive • oslo.config Configuration Generator • oslo.policy Directive • oslo.policy Configuration Generator • cliff Directive • stevedore Directive