OpenStack + Sphinx In A Tree

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

Transcript

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

   View Slide

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

   View Slide

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

   View Slide

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

   View Slide

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

   View Slide

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

   View Slide

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),
   ]
   

   View Slide

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

   View Slide

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

   View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

17. Stevedore
    A single directive for listing plugins for an entrypoint
    

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide