From 423890a4950a725d6b493304d7b933d5b7c090d7 Mon Sep 17 00:00:00 2001 From: Akihiro Motoki Date: Sun, 21 May 2017 00:59:46 +0900 Subject: [PATCH] doc: autogenerate OSC plugin command reference Recently cliff introduced a sphinx extension directive named autoprogram-cliff which genarates command-line help automatically. By using it, we no longer need to write command-line help document separately. Also fixes minor string substitution issue in a BGPVPN command. Note that the new cliff release with the directive is not released yet, but there are several number of OSC plugin commands proposed and having a local copy would help such developers. Change-Id: I6b1aee89f406ac449fbc43e210c4ca7ad901b19b --- doc/source/cli/osc/v2/firewall-group.rst | 228 +---------- doc/source/cli/osc/v2/firewall-policy.rst | 264 +----------- doc/source/cli/osc/v2/firewall-rule.rst | 296 +------------- doc/source/cli/osc/v2/network-trunk.rst | 173 +------- doc/source/cli/osc/v2/networking-bgpvpn.rst | 381 +----------------- doc/source/conf.py | 15 +- neutronclient/cliff_sphinxext.py | 307 ++++++++++++++ .../osc/v2/networking_bgpvpn/bgpvpn.py | 2 +- 8 files changed, 358 insertions(+), 1308 deletions(-) create mode 100644 neutronclient/cliff_sphinxext.py diff --git a/doc/source/cli/osc/v2/firewall-group.rst b/doc/source/cli/osc/v2/firewall-group.rst index b0c24a884..adb8d05d3 100644 --- a/doc/source/cli/osc/v2/firewall-group.rst +++ b/doc/source/cli/osc/v2/firewall-group.rst @@ -8,223 +8,23 @@ router ports within a project. Network v2 -firewall group create ---------------------- +.. 'firewall group *' cannot be used below as it matches 'firewall group rule + *' or 'firewall group policy *'. -Create a firewall group for a given project. +.. autoprogram-cliff:: openstack.neutronclient.v2 + :command: firewall group create -.. program:: firewall group create -.. code:: bash +.. autoprogram-cliff:: openstack.neutronclient.v2 + :command: firewall group delete - openstack firewall group create +.. autoprogram-cliff:: openstack.neutronclient.v2 + :command: firewall group list -.. _firewallgroup_create-firewallgroup: -.. option:: --name +.. autoprogram-cliff:: openstack.neutronclient.v2 + :command: firewall group set - Name for the firewall group. +.. autoprogram-cliff:: openstack.neutronclient.v2 + :command: firewall group show -.. option:: --enable - - Enable firewall group (default). - -.. option:: --disable - - Disable firewall group. - -.. option:: --public - - Make the firewall group public, which allows it to be used in all projects - (as opposed to the default, which is to restrict its use to the current - project). - -.. option:: --private - - Restrict use of the firewall group to the current project. - -.. option:: --project - - Owner's project (name or ID). - -.. option:: --project-domain - - Domain the project belongs to (name or ID). - This can be used in case collisions between project names exist. - -.. option:: --description - - A description of the firewall group. - -.. option:: --ingress-firewall-policy - - Ingress firewall policy (name or ID). - -.. option:: --no-ingress-firewall-policy - - Detach ingress firewall policy from the firewall group. - -.. option:: --egress-firewall-policy - - Egress firewall policy (name or ID). - -.. option:: --no-egress-firewall-policy - - Detach egress firewall policy from the firewall group. - -.. option:: --port - - Port(s) to apply firewall group (name or ID). - -.. option:: --no-port - - Detach all port from the firewall group. - -firewall group delete ---------------------- - -Delete firewall group(s) - -.. program:: firewall group delete -.. code:: bash - - openstack firewall group delete - [ ...] - -.. _firewallgroup_delete-firewallgroup: -.. describe:: - - Firewall group(s) to delete (name or ID). - -firewall group list -------------------- - -List all firewall groups - -.. program:: firewall group list -.. code:: bash - - openstack firewall group list - [--long] - -.. option:: --long - - List additional fields in output. - -firewall group set ------------------- - -Set firewall group properties - -.. program:: firewall group set -.. code:: bash - - openstack firewall group set - -.. _firewallgroup_set-firewallgroup: -.. describe:: - - Firewall group to set (name or ID). - -.. option:: --name - - Set firewall group name. - -.. option:: --enable - - Enable firewall group (default). - -.. option:: --disable - - Disable firewall group. - -.. option:: --public - - Make the firewall group public, which allows it to be used in all projects - (as opposed to the default, which is to restrict its use to the current - project). - -.. option:: --private - - Restrict use of the firewall group to the current project. - -.. option:: --description - - A description of the firewall group. - -.. option:: --ingress-firewall-policy - - Ingress firewall policy (name or ID). - -.. option:: --no-ingress-firewall-policy - - Detach ingress firewall policy from the firewall group. - -.. option:: --egress-firewall-policy - - Egress firewall policy (name or ID). - -.. option:: --no-egress-firewall-policy - - Detach egress firewall policy from the firewall group. - -.. option:: --port - - Port(s) to apply firewall group. - -.. option:: --no-port - - Detach all port from the firewall group. - -firewall group show -------------------- - -Show information of a given firewall group - -.. program:: firewall group show -.. code:: bash - - openstack firewall group show - - -.. _firewallgroup_show-firewallgroup: -.. describe:: - - Firewall group to display (name or ID). - -firewall group unset --------------------- - -Unset firewall group properties - -.. program:: firewall group unset -.. code:: bash - - openstack firewall group unset - -.. _firewallgroup_unset-firewallgroup: -.. describe:: - - Firewall group to unset (name or ID). - -.. option:: --enable - - Disable firewall group. - -.. option:: --public - - Restrict use of the firewall group to the current project. - -.. option:: --ingress-firewall-policy - - Detach ingress firewall policy from the firewall group. - -.. option:: --egress-firewall-policy - - Detach egress firewall policy from the firewall group. - -.. option:: --port - - Remove port(s) from the firewall group. - -.. option:: --all-port - - Remove all ports from the firewall group. +.. autoprogram-cliff:: openstack.neutronclient.v2 + :command: firewall group unset diff --git a/doc/source/cli/osc/v2/firewall-policy.rst b/doc/source/cli/osc/v2/firewall-policy.rst index c4a78dd07..f05f83451 100644 --- a/doc/source/cli/osc/v2/firewall-policy.rst +++ b/doc/source/cli/osc/v2/firewall-policy.rst @@ -10,265 +10,5 @@ which create or use the firewall group policy). Network v2 -firewall group policy create ----------------------------- - -Create a firewall policy for a given project - -.. program:: firewall group policy create -.. code:: bash - - openstack firewall group policy create - -.. _firewallpolicy_create-firewallpolicy: -.. describe:: - - Name for the firewall policy. - -.. option:: --enable - - Enable firewall policy (default). - -.. option:: --disable - - Disable firewall policy. - -.. option:: --public - - Make the firewall policy public, which allows it to be used in all projects - (as opposed to the default, which is to restrict its use to the current - project). - -.. option:: --private - - Restrict use of the firewall policy to the current project. - -.. option:: --project - - Owner's project (name or ID). - -.. option:: --project-domain - - Domain the project belongs to (name or ID). - This can be used in case collisions between project names exist. - -.. option:: --description - - A description of the firewall policy. - -.. option:: --firewall-rule - - Firewall rule(s) to apply (name or ID). - -.. option:: --no-firewall-rule - - Remove all firewall rules from the firewall policy. - -.. option:: --audited - - Enable auditing for the policy. - -.. option:: --no-audited - - Disable auditing for the policy. - - -firewall group policy delete ----------------------------- - -Delete a given firewall policy - -.. program:: firewall group policy delete -.. code:: bash - - openstack firewall group policy delete - [ ...] - -.. _firewallpolicy_delete-firewallpolicy: -.. describe:: - - Firewall policy(s) to delete (name or ID). - -firewall group policy list --------------------------- - -List all firewall policies - -.. program:: firewall group policy list -.. code:: bash - - openstack firewall group policy list - [--long] - -.. option:: --long - - List additional fields in output. - -firewall group policy set -------------------------- - -Set firewall policy properties - -.. program:: firewall group policy set -.. code:: bash - - openstack firewall group policy set - -.. _firewallpolicy_set-firewallpolicy: -.. describe:: - - Firewall policy to set (name or ID). - -.. option:: --name - - Set firewall policy name. - -.. option:: --enable - - Enable firewall policy (default). - -.. option:: --disable - - Disable firewall policy. - -.. option:: --public - - Make the firewall policy public, which allows it to be used in all projects - (as opposed to the default, which is to restrict its use to the current - project). - -.. option:: --private - - Restrict use of the firewall policy to the current project. - -.. option:: --project - - Owner's project (name or ID). - -.. option:: --project-domain - - Domain the project belongs to (name or ID). - This can be used in case collisions between project names exist. - -.. option:: --description - - A description of the firewall policy. - -.. option:: --firewall-rule - - Firewall rule(s) to apply (name or ID). - -.. option:: --no-firewall-rule - - Unset all firewall rules from firewall policy. - -.. option:: --audited - - Enable auditing for the policy. - -.. option:: --no-audited - - Disable auditing for the policy. - - -firewall group policy show --------------------------- - -Show information of a given firewall policy - -.. program:: firewall group policy show -.. code:: bash - - openstack firewall group policy show - - -.. _firewallpolicy_show-firewallpolicy: -.. describe:: - - Firewall policy to display (name or ID). - -firewall group policy unset ---------------------------- - -Unset firewall policy properties - -.. program:: firewall group policy unset -.. code:: bash - - openstack firewall group policy unset - -.. _firewallpolicy_unset-firewallpolicy: -.. describe:: - - Firewall policy to unset (name or ID). - -.. option:: --enable - - Disable firewall policy. - -.. option:: --public - - Restrict use of the firewall policy to the current project. - -.. option:: --firewall-rule - - Firewall rule(s) to unset (name or ID). - -.. option:: --all-firewall-rule - - Remove all firewall rules from the firewall policy. - -.. option:: --audited - - Disable auditing for the policy. - -firewall group policy add rule ------------------------------- - -Adds a firewall rule in a firewall policy relative to the position of other -rules. - -.. program:: firewall group policy add rule -.. code:: bash - - openstack firewall group policy add rule - - - -.. _firewallpolicy_add_rule-firewallpolicy: -.. describe:: - - Firewall policy to add rule (name or ID). - -.. describe:: - - Firewall rule to be inserted (name or ID). - -.. option:: --insert-after - - Insert the new rule after this existing rule (name or ID). - -.. option:: --insert-before - - Insert the new rule before this existing rule (name or ID). - -firewall group policy remove rule ---------------------------------- - -Removes a firewall rule from a firewall policy. - -.. program:: firewall group policy remove rule -.. code:: bash - - openstack firewall group policy remove rule - - - -.. _firewallpolicy_remove_rule-firewallpolicy: -.. describe:: - - Firewall policy to remove rule (name or ID). - -.. describe:: - - Firewall rule to remove from policy (name or ID). +.. autoprogram-cliff:: openstack.neutronclient.v2 + :command: firewall group policy * diff --git a/doc/source/cli/osc/v2/firewall-rule.rst b/doc/source/cli/osc/v2/firewall-rule.rst index fdb520684..2e75c775f 100644 --- a/doc/source/cli/osc/v2/firewall-rule.rst +++ b/doc/source/cli/osc/v2/firewall-rule.rst @@ -8,297 +8,5 @@ be taken on the matched data traffic. Network v2 -firewall group rule create --------------------------- - -Create a firewall rule for a given project - -.. program:: firewall group rule create -.. code:: bash - - openstack firewall group rule create - -.. option:: --name - - Set firewall rule name. - -.. option:: --enable - - Enable firewall rule (default). - -.. option:: --disable - - Disable firewall rule. - -.. option:: --public - - Make the firewall rule public, which allows it to be used in all projects - (as opposed to the default, which is to restrict its use to the current - project). - -.. option:: --private - - Restrict use of the firewall rule to the current project. - -.. option:: --project - - Owner's project (name or ID) - -.. option:: --project-domain - - Domain the project belongs to (name or ID). - This can be used in case collisions between project names exist. - -.. option:: --description - - A description of the firewall rule. - -.. option:: --protocol - - Protocol for the firewall rule ('tcp', 'udp', 'icmp', 'any'). - Default is 'any'. - -.. option:: --action - - Action for the firewall rule ('allow', 'deny', 'reject'). - Default is 'deny'. - -.. option:: --ip-version - - Set IP version 4 or 6 (default is 4). - -.. option:: --source-port - - Source port number or range - (integer in [1, 65535] or range like 123:456). - -.. option:: --no-source-port - - Detach source port number or range. - -.. option:: --destination-port - - Destination port number or range - (integer in [1, 65535] or range like 123:456). - -.. option:: --no-destination-port - - Detach destination port number or range. - -.. option:: --source-ip-address - - Source IP address or subnet. - -.. option:: --no-source-ip-address - - Detach source IP address. - -.. option:: --destination-ip-address - - Destination IP address or subnet. - -.. option:: --no-destination-ip-address - - Detach destination IP address. - -.. option:: --enable-rule - - Enable this rule (default is enabled). - -.. option:: --disable-rule - - Disable this rule. - -firewall group rule delete --------------------------- - -Delete a given firewall rule - -.. program:: firewall group rule delete -.. code:: bash - - openstack firewall group rule delete - [ ...] - -.. _firewallrule_delete-firewallrule: -.. describe:: - - Firewall rule(s) to delete (name or ID). - -firewall group rule list ------------------------- - -List all firewall rules - -.. program:: firewall group rule list -.. code:: bash - - openstack firewall group rule list - [--long] - -.. option:: --long - - List additional fields in output. - -firewall group rule set ------------------------ - -Set firewall rule properties - -.. program:: firewall group rule set -.. code:: bash - - openstack firewall group rule set - -.. _firewallrule_set-firewallrule: -.. describe:: - - Firewall rule to set (name or ID). - -.. option:: --name - - Set firewall rule name. - -.. option:: --enable - - Enable firewall rule (default). - -.. option:: --disable - - Disable firewall rule. - -.. option:: --public - - Make the firewall rule public, which allows it to be used in all projects - (as opposed to the default, which is to restrict its use to the current - project). - -.. option:: --private - - Restrict use of the firewall rule to the current project. - -.. option:: --project - - Owner's project (name or ID). - -.. option:: --project-domain - - Domain the project belongs to (name or ID). - This can be used in case collisions between project names exist. - -.. option:: --description - - A description of the firewall rule. - -.. option:: --protocol - - Protocol for the firewall rule ('tcp', 'udp', 'icmp', 'any'). - -.. option:: --action - - Action for the firewall rule ('allow', 'deny', 'reject'). - -.. option:: --ip-version - - Set IP version 4 or 6 (default is 4). - -.. option:: --source-port - - Source port number or range - (integer in [1, 65535] or range like 123:456). - -.. option:: --no-source-port - - Detach source port number or range. - -.. option:: --destination-port - - Destination port number or range - (integer in [1, 65535] or range like 123:456). - -.. option:: --no-destination-port - - Detach destination port number or range. - -.. option:: --source-ip-address - - Source IP address or subnet. - -.. option:: --no-source-ip-address - - Detach source IP address. - -.. option:: --destination-ip-address - - Destination IP address or subnet. - -.. option:: --no-destination-ip-address - - Detach destination IP address. - -.. option:: --enable-rule - - Enable this rule (default is enabled). - -.. option:: --disable-rule - - Disable this rule. - -firewall group rule show ------------------------- - -Show information of a given firewall rule - -.. program:: firewall group rule show -.. code:: bash - - openstack firewall group rule show - - -.. _firewallrule_show-firewallrule: -.. describe:: - - Firewall rule to display (name or ID). - -firewall group rule unset -------------------------- - -Unset firewall rule properties - -.. program:: firewall group rule unset -.. code:: bash - - openstack firewall group rule unset - -.. _firewallrule_unset-firewallrule: -.. describe:: - - Firewall rule to unset (name or ID). - -.. option:: --enable - - Disable firewall rule. - -.. option:: --public - - Restrict use of the firewall rule to the current project. - -.. option:: --source-port - - Detach source port number or range. - -.. option:: --destination-port - - Detach destination port number or range. - -.. option:: --source-ip-address - - Detach source IP address. - -.. option:: --destination-ip-address - - Detach destination IP address. - -.. option:: --enable-rule - - Disable this rule. +.. autoprogram-cliff:: openstack.neutronclient.v2 + :command: firewall group rule * diff --git a/doc/source/cli/osc/v2/network-trunk.rst b/doc/source/cli/osc/v2/network-trunk.rst index 06a63d209..22144a4ee 100644 --- a/doc/source/cli/osc/v2/network-trunk.rst +++ b/doc/source/cli/osc/v2/network-trunk.rst @@ -9,173 +9,8 @@ the server to connect to more networks. Network v2 -network subport list --------------------- +.. autoprogram-cliff:: openstack.neutronclient.v2 + :command: network subport list -List all subports for a given network trunk - -.. program:: network subport list -.. code:: bash - - openstack network subport list - --trunk - -.. option:: --trunk - - List subports belonging to this trunk (name or ID) (required) - -network trunk create --------------------- - -Create a network trunk for a given project - -.. program:: network trunk create -.. code:: bash - - openstack network trunk create - --parent-port - [--subport ] - [--enable | --disable] - [--project [--project-domain ]] - [--description ] - - -.. option:: --parent-port - - Parent port belonging to this trunk (name or ID) (required) - -.. option:: --subport - - Subport to add. Subport is of form 'port=,segmentation-type=,segmentation-ID=' - (--subport) option can be repeated - -.. option:: --enable - - Enable trunk (default) - -.. option:: --disable - - Disable trunk - -.. option:: --project - - Owner's project (name or ID) - -.. option:: --project-domain - - Domain the project belongs to (name or ID). - This can be used in case collisions between project names exist. - -.. option:: --description - - A description of the trunk. - -network trunk delete --------------------- - -Delete a given network trunk - -.. program:: network trunk delete -.. code:: bash - - openstack network trunk delete - [ ...] - -.. _network_trunk_delete-trunk: -.. describe:: - - Trunk(s) to delete (name or ID) - -network trunk list ------------------- - -List all network trunks - -.. program:: network trunk list -.. code:: bash - - openstack network trunk list - [--long] - -.. option:: --long - - List additional fields in output - -network trunk set ------------------ - -Set network trunk properties - -.. program:: network trunk set -.. code:: bash - - openstack network trunk set - [--name ] - [--description ] - [--subport ] - [--enable | --disable] - - -.. option:: --name - - Set trunk name - -.. option:: --description - - A description of the trunk. - -.. option:: --subport - - Subport to add. Subport is of form 'port=,segmentation-type=,segmentation-ID=' - (--subport) option can be repeated - -.. option:: --enable - - Enable trunk - -.. option:: --disable - - Disable trunk - -.. _network_trunk_set-trunk: -.. describe:: - - Trunk to modify (name or ID) - -network trunk show ------------------- - -Show information of a given network trunk - -.. program:: network trunk show -.. code:: bash - - openstack network trunk show - - -.. _network_trunk_show-trunk: -.. describe:: - - Trunk to display (name or ID) - -network trunk unset -------------------- - -Unset subports from a given network trunk - -.. program:: network trunk unset -.. code:: bash - - openstack network trunk unset - --subport - - -.. option:: --subport - - Subport to delete (name or ID of the port) (required) - (--subport) option can be repeated - -.. _network_trunk_unset-trunk: -.. describe:: - - Unset subports from this trunk (name or ID) +.. autoprogram-cliff:: openstack.neutronclient.v2 + :command: network trunk * diff --git a/doc/source/cli/osc/v2/networking-bgpvpn.rst b/doc/source/cli/osc/v2/networking-bgpvpn.rst index 69b3150db..371e47287 100644 --- a/doc/source/cli/osc/v2/networking-bgpvpn.rst +++ b/doc/source/cli/osc/v2/networking-bgpvpn.rst @@ -9,375 +9,26 @@ between L3VPNs and Neutron resources, i.e. Networks, Routers and Ports. Network v2 -bgpvpn create -------------- +.. autoprogram-cliff:: openstack.neutronclient.v2 + :command: bgpvpn create -Create a BGP VPN resource for a given project +.. autoprogram-cliff:: openstack.neutronclient.v2 + :command: bgpvpn delete -.. program:: bgpvpn create -.. code:: bash +.. autoprogram-cliff:: openstack.neutronclient.v2 + :command: bgpvpn list - openstack bgpvpn create +.. autoprogram-cliff:: openstack.neutronclient.v2 + :command: bgpvpn set -.. _bgpvpn_create-bgpvpn: -.. option:: --project +.. autoprogram-cliff:: openstack.neutronclient.v2 + :command: bgpvpn show - Owner's project (name or ID) +.. autoprogram-cliff:: openstack.neutronclient.v2 + :command: bgpvpn unset -.. option:: --project-domain +.. autoprogram-cliff:: openstack.neutronclient.v2 + :command: bgpvpn network association * - Domain the project belongs to (name or ID). This can be used in case - collisions between project names exist - -.. option:: --name - - Name for the BGP VPN. - -.. option:: --route-target - - Add Route Target to import list (repeat option for multiple Route Targets) - -.. option:: --import-target - - Add Route Target to import list (repeat option for multiple Route Targets) - -.. option:: --export-target - - Add Route Target to export list (repeat option for multiple RouteTargets) - -.. option:: --route-distinguisher - - Add Route Distinguisher to the list of Route Distinguishers from which a - Route Distinguishers will be picked from to advertise a VPN route (repeat - option for multiple Route Distinguishers) - -.. option:: --type {l2,l3} - - BGP VPN type selection between IP VPN (l3) and Ethernet VPN (l2) - (default: l3) - -bgpvpn set ----------- - -Set BGP VPN properties - -.. program:: bgpvpn set -.. code:: bash - - openstack bgpvpn set - -.. _bgpvpn_set-bgpvpn: -.. describe:: - - BGP VPN to update (name or ID) - -.. option:: --name - - Name for the BGP VPN - -.. option:: --route-target - - Add Route Target to import list (repeat option for multiple Route Targets) - -.. option:: --no-route-target - - Empty route target list. - -.. option:: --import-target - - Add Route Target to import list (repeat option for multiple Route Targets) - -.. option:: --no-import-target - - Empty import route target list - -.. option:: --export-target - - Add Route Target to export list (repeat option for multiple Route Targets) - -.. option:: --no-export-target - - Empty export route target list - -.. option:: --route-distinguisher - - Add Route Distinguisher to the list of Route Distinguishers from which a - Route Distinguishers will be picked from to advertise a VPN route (repeat - option for multiple Route Distinguishers) - -.. option:: --no-route-distinguisher - - Empty route distinguisher list - -bgpvpn unset ------------- - -Unset BGP VPN properties - -.. program:: bgpvpn unset -.. code:: bash - - openstack bgpvpn unset - -.. _bgpvpn_unset-bgpvpn: -.. describe:: - - BGP VPN to update (name or ID) - -.. option:: --route-target - - Remove Route Target from import/export list (repeat option for multiple - Route Targets) - -.. option:: --all-route-target - - Empty route target list - -.. option:: --import-target - - Remove Route Target from import list (repeat option for multiple Route - Targets) - -.. option:: --all-import-target - - Empty import route target list - -.. option:: --export-target - - Remove Route Target from export list (repeat option for multiple Route - Targets) - -.. option:: --all-export-target - - Empty export route target list - -.. option:: --route-distinguisher - - Remove Route Distinguisher from the list of Route Distinguishers from which - a Route Distinguishers will be picked from to advertise a VPN route - (repeat option for multiple Route Distinguishers) - -.. option:: --all-route-distinguisher - - Empty route distinguisher list - -bgpvpn delete -------------- - -Delete BGP VPN resource(s) - -.. program:: bgpvpn delete -.. code:: bash - - openstack bgpvpn delete - [ ...] - -.. _bgpvpn_delete-bgpvpn: -.. describe:: - BGP VPN(s) to delete (name or ID) - -bgpvpn list ------------ - -List BGP VPN resources - -.. program:: bgpvpn list -.. code:: bash - - openstack bgpvpn list - -.. _bgpvpn_list-bgpvpn: -.. option:: --project - - Owner's project (name or ID) - -.. option:: --project-domain - - Domain the project belongs to (name or ID). This can be used in case - collisions between project names exist. - -.. option:: --long - - List additional fields in output - -.. option:: --property - - Filter property to apply on returned BGP VPNs (repeat to filter on multiple - properties) - -bgpvpn show ------------ - -Show information of a given BGP VPN - -.. program:: bgpvpn show -.. code:: bash - - openstack bgpvpn show - -.. _bgpvpn_show-bgpvpn: -.. describe:: - - BGP VPN to display (name or ID) - -bgpvpn network association create ---------------------------------- - -Create a BGP VPN network association - -.. program:: bgpvpn network association create -.. code:: bash - - openstack bgpvpn network association create - -.. _bgpvpn_net-assoc_create-bgpvpn: -.. describe:: - - ID or name of the BGP VPN - -.. describe:: - - ID or name of the network - -.. option:: --project - - Owner's project (name or ID) - -.. option:: --project-domain - - Domain the project belongs to (name or ID). This can be used in case - collisions between project names exist. - -bgpvpn network association delete ---------------------------------- - -Remove a BGP VPN network association(s) for a given BGP VPN - -.. program:: bgpvpn network association delete -.. code:: bash - - openstack bgpvpn network association delete - [ ...] - -.. _bgpvpn_net-assoc_delete-bgpvpn: -.. describe:: - ID(s) of the network association(s) to remove - -.. describe:: - ID or name of the BGP VPN - -bgpvpn network association list -------------------------------- - -List BGP VPN network associations for a given BGP VPN - -.. program:: bgpvpn network association list -.. code:: bash - - openstack bgpvpn network association list - -.. _bgpvpn_net-assoc_list-bgpvpn: -.. describe:: - ID or name of the BGP VPN - -.. option:: --long - - List additional fields in output - -bgpvpn network association show -------------------------------- - -Show information of a given BGP VPN network association - -.. program:: bgpvpn network association show -.. code:: bash - - openstack bgpvpn network association show - -.. _bgpvpn_net-assoc_show-bgpvpn: -.. describe:: - ID of the network association to look up - -.. describe:: - BGP VPN the association belongs to (name or ID) - -bgpvpn router association create --------------------------------- - -Create a BGP VPN router association - -.. program:: bgpvpn router association create -.. code:: bash - - openstack bgpvpn router association create - -.. _bgpvpn_router-assoc_create-bgpvpn: -.. describe:: - - ID or name of the BGP VPN - -.. describe:: - - ID or name of the router. - -.. option:: --project - - Owner's project (name or ID) - -.. option:: --project-domain - - Domain the project belongs to (name or ID). This can be used in case - collisions between project names exist. - -bgpvpn router association delete --------------------------------- - -Delete a BGP VPN router association(s) for a given BGP VPN - -.. program:: bgpvpn router association delete -.. code:: bash - - openstack bgpvpn router association delete - [ ...] - -.. _bgpvpn_router-assoc_delete-bgpvpn: -.. describe:: - ID(s) of the router association(s) to delete. - -.. describe:: - ID or name of the BGP VPN - -bgpvpn router association list ------------------------------- - -List BGP VPN router associations for a given BGP VPN - -.. program:: bgpvpn router association list -.. code:: bash - - openstack bgpvpn router association list - -.. _bgpvpn_router-assoc_list-bgpvpn: -.. describe:: - ID or name of the BGP VPN - -.. option:: --long - - List additional fields in output - -bgpvpn router association show ------------------------------- - -Show information of a given BGP VPN router association - -.. program:: bgpvpn router association show -.. code:: bash - - openstack bgpvpn router association show - -.. _bgpvpn_router-assoc_show-bgpvpn: -.. describe:: - ID of the router association to look up - -.. describe:: - BGP VPN the association belongs to (name or ID) +.. autoprogram-cliff:: openstack.neutronclient.v2 + :command: bgpvpn router association * diff --git a/doc/source/conf.py b/doc/source/conf.py index 4043a8266..1bcb1db59 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -5,9 +5,14 @@ # 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', - 'reno.sphinxext', - 'openstackdocstheme', +extensions = [ + 'sphinx.ext.autodoc', + 'reno.sphinxext', + 'openstackdocstheme', + # 'cliff.sphinxext', + # TODO(amotoki): Switch to cliff.sphinxext once cliff bug is fixed. + # https://bugs.launchpad.net/python-cliff/+bug/1692018 + 'neutronclient.cliff_sphinxext', ] # openstackdocstheme options @@ -46,3 +51,7 @@ html_theme = 'openstackdocs' # Output file base name for HTML help builder. htmlhelp_basename = 'neutronclientdoc' + +# -- Options for cliff.sphinxext plugin --------------------------------------- + +autoprogram_cliff_application = 'openstack' diff --git a/neutronclient/cliff_sphinxext.py b/neutronclient/cliff_sphinxext.py new file mode 100644 index 000000000..16915fac0 --- /dev/null +++ b/neutronclient/cliff_sphinxext.py @@ -0,0 +1,307 @@ +# Copyright (C) 2017, Red Hat, Inc. +# +# Licensed under the Apache License, Version 2.0 (the "License"); you may +# not use this file except in compliance with the License. You may obtain +# a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +# License for the specific language governing permissions and limitations +# under the License. + +import argparse +import fnmatch +import re + +from docutils import nodes +from docutils.parsers import rst +from docutils.parsers.rst import directives +from docutils import statemachine + +from cliff import commandmanager + + +def _indent(text): + """Indent by four spaces.""" + prefix = ' ' * 4 + + def prefixed_lines(): + for line in text.splitlines(True): + yield (prefix + line if line.strip() else line) + + return ''.join(prefixed_lines()) + + +def _format_description(parser): + """Get parser description. + + We parse this as reStructuredText, allowing users to embed rich + information in their help messages if they so choose. + """ + for line in statemachine.string2lines( + parser.description, tab_width=4, convert_whitespace=True): + yield line + + +def _format_usage(parser): + """Get usage without a prefix.""" + fmt = argparse.HelpFormatter(parser.prog) + + optionals = parser._get_optional_actions() + positionals = parser._get_positional_actions() + groups = parser._mutually_exclusive_groups + + # hacked variant of the regex used by the actual argparse module. Unlike + # that version, this one attempts to group long and short opts with their + # optional arguments ensuring that, for example, '---format ' + # becomes ['--format '] and not ['--format', '']. + # Yes, they really do use regexes to break apart and rewrap their help + # string. Don't ask me why. + part_regexp = r'\(.*?\)+|\[.*?\]+|(?:(?:-\w|--\w+)(?:\s+<\w+>)?)|\S+' + + opt_usage = fmt._format_actions_usage(optionals, groups) + pos_usage = fmt._format_actions_usage(positionals, groups) + + opt_parts = re.findall(part_regexp, opt_usage) + pos_parts = re.findall(part_regexp, pos_usage) + parts = opt_parts + pos_parts + + if len(' '.join([parser.prog] + parts)) < 72: + return [' '.join([parser.prog] + parts)] + + return [parser.prog] + [_indent(x) for x in parts] + + +def _format_epilog(parser): + """Get parser epilog. + + We parse this as reStructuredText, allowing users to embed rich + information in their help messages if they so choose. + """ + for line in statemachine.string2lines( + parser.epilog, tab_width=4, convert_whitespace=True): + yield line + + +def _format_positional_action(action): + """Format a positional action.""" + if action.help == argparse.SUPPRESS: + return + + # NOTE(stephenfin): We strip all types of brackets from 'metavar' because + # the 'option' directive dictates that only option argument names should be + # surrounded by angle brackets + yield '.. option:: {}'.format( + (action.metavar or action.dest).strip('<>[]() ')) + if action.help: + yield '' + for line in statemachine.string2lines( + action.help, tab_width=4, convert_whitespace=True): + yield _indent(line) + + +def _format_optional_action(action): + """Format an optional action.""" + if action.help == argparse.SUPPRESS: + return + + if action.nargs == 0: + yield '.. option:: {}'.format(', '.join(action.option_strings)) + else: + # TODO(stephenfin): At some point, we may wish to provide more + # information about the options themselves, for example, if nargs is + # specified + option_strings = [' '.join( + [x, action.metavar or '<{}>'.format(action.dest.upper())]) + for x in action.option_strings] + yield '.. option:: {}'.format(', '.join(option_strings)) + + if action.help: + yield '' + for line in statemachine.string2lines( + action.help, tab_width=4, convert_whitespace=True): + yield _indent(line) + + +def _format_parser(parser): + """Format the output of an argparse 'ArgumentParser' object. + + Given the following parser:: + + >>> import argparse + >>> parser = argparse.ArgumentParser(prog='hello-world', \ + description='This is my description.', + epilog='This is my epilog') + >>> parser.add_argument('name', help='User name', metavar='') + >>> parser.add_argument('--language', action='store', dest='lang', \ + help='Greeting language') + + Returns the following:: + + This is my description. + + .. program:: hello-world + .. code:: shell + + hello-world [-h] [--language LANG] + + .. option:: name + + User name + + .. option:: --language LANG + + Greeting language + + .. option:: -h, --help + + Show this help message and exit + + This is my epilog. + """ + if parser.description: + for line in _format_description(parser): + yield line + yield '' + + yield '.. program:: {}'.format(parser.prog) + + yield '.. code-block:: shell' + yield '' + for line in _format_usage(parser): + yield _indent(line) + yield '' + + # In argparse, all arguments and parameters are known as "actions". + # Optional actions are what would be known as flags or options in other + # libraries, while positional actions would generally be known as + # arguments. We present these slightly differently. + + for action in parser._get_optional_actions(): + for line in _format_optional_action(action): + yield line + yield '' + + for action in parser._get_positional_actions(): + for line in _format_positional_action(action): + yield line + yield '' + + if parser.epilog: + for line in _format_epilog(parser): + yield line + yield '' + + +class AutoprogramCliffDirective(rst.Directive): + """Auto-document a subclass of `cliff.command.Command`.""" + + has_content = False + required_arguments = 1 + option_spec = { + 'command': directives.unchanged, + 'ignored': directives.unchanged, + 'application': directives.unchanged, + } + + def _load_command(self, manager, command_name): + """Load a command using an instance of a `CommandManager`.""" + try: + # find_command expects the value of argv so split to emulate that + return manager.find_command(command_name.split())[0] + except ValueError: + raise self.error('"{}" is not a valid command in the "{}" ' + 'namespace'.format( + command_name, manager.namespace)) + + def _generate_nodes(self, title, command_name, command_class, + ignored_opts): + """Generate the relevant Sphinx nodes. + + This is a little funky. Parts of this use raw docutils nodes while + other parts use reStructuredText and nested parsing. The reason for + this is simple: it avoids us having to reinvent the wheel. While raw + docutils nodes are helpful for the simpler elements of the output, + they don't provide an easy way to use Sphinx's own directives, such as + the 'option' directive. Refer to [1] for more information. + + [1] http://www.sphinx-doc.org/en/stable/extdev/markupapi.html + + :param title: Title of command + :param command_name: Name of command, as used on the command line + :param command_class: Subclass of :py:class:`cliff.command.Command` + :param prefix: Prefix to apply before command, if any + :param ignored_opts: A list of options to exclude from output, if any + :returns: A list of nested docutil nodes + """ + command = command_class(None, None) + parser = command.get_parser(command_name) + ignored_opts = ignored_opts or [] + + # Drop the automatically-added help action + for action in list(parser._actions): + for option_string in action.option_strings: + if option_string in ignored_opts: + del parser._actions[parser._actions.index(action)] + break + + section = nodes.section( + '', + nodes.title(text=title), + ids=[nodes.make_id(title)], + names=[nodes.fully_normalize_name(title)]) + + source_name = '<{}>'.format(command.__class__.__name__) + result = statemachine.ViewList() + + for line in _format_parser(parser): + result.append(line, source_name) + + self.state.nested_parse(result, 0, section) + + return [section] + + def run(self): + self.env = self.state.document.settings.env + + command_pattern = self.options.get('command') + application_name = (self.options.get('application') + or self.env.config.autoprogram_cliff_application) + + global_ignored = self.env.config.autoprogram_cliff_ignored + local_ignored = self.options.get('ignored', '') + local_ignored = [x.strip() for x in local_ignored.split(',') + if x.strip()] + ignored_opts = list(set(global_ignored + local_ignored)) + + # TODO(sfinucan): We should probably add this wildcarding functionality + # to the CommandManager itself to allow things like "show me the + # commands like 'foo *'" + manager = commandmanager.CommandManager(self.arguments[0]) + if command_pattern: + commands = [x for x in manager.commands + if fnmatch.fnmatch(x, command_pattern)] + else: + commands = manager.commands.keys() + + output = [] + for command_name in sorted(commands): + command_class = self._load_command(manager, command_name) + + title = command_name + if application_name: + command_name = ' '.join([application_name, command_name]) + + output.extend(self._generate_nodes( + title, command_name, command_class, ignored_opts)) + + return output + + +def setup(app): + app.add_directive('autoprogram-cliff', AutoprogramCliffDirective) + app.add_config_value('autoprogram_cliff_application', '', True) + app.add_config_value('autoprogram_cliff_ignored', ['--help'], True) diff --git a/neutronclient/osc/v2/networking_bgpvpn/bgpvpn.py b/neutronclient/osc/v2/networking_bgpvpn/bgpvpn.py index 96d72ddfe..ab49c2ff5 100644 --- a/neutronclient/osc/v2/networking_bgpvpn/bgpvpn.py +++ b/neutronclient/osc/v2/networking_bgpvpn/bgpvpn.py @@ -216,7 +216,7 @@ class CreateBgpvpn(command.ShowOne): default='l3', choices=['l2', 'l3'], help=_("BGP VPN type selection between IP VPN (l3) and Ethernet " - "VPN (l2) (default: %(default)s)"), + "VPN (l2) (default: l3)"), ) return parser