Convert API Reference to RST and host it in the Nova tree (partial)

Registered by Sean Dague on 2016-03-29

The current API Reference website is based on a baroque publish toolchain using WADL and Maven, which is largely unmaintained. This makes it hard to have an up to date version of our API docs, or describe things like microversions in our docs.

There is a push to convert this to RST instead. We'll be doing that in the nova tree first to demonstrate this working, then export to other projects.

Blueprint information

Status:
Complete
Approver:
Matt Riedemann
Priority:
Medium
Drafter:
Sean Dague
Direction:
Approved
Assignee:
Sean Dague
Definition:
Approved
Series goal:
Accepted for newton
Implementation:
Implemented
Milestone target:
milestone icon newton-3
Started by
Matt Riedemann on 2016-03-29
Completed by
Matt Riedemann on 2016-09-16

Whiteboard

Gerrit topic: https://review.openstack.org/#q,topic:bp/api-ref-in-rst,n,z

Addressed by: https://review.openstack.org/305769
    Add 'Show All' / 'Hide All' toggle

Addressed by: https://review.openstack.org/305783
    fix blockquote font size

Addressed by: https://review.openstack.org/305358
    Fix css references to the glyphicons font

Addressed by: https://review.openstack.org/305406
    use 'required' instead of 'optional' for parameters

Addressed by: https://review.openstack.org/305987
    move sphinx h3 to '-' instead of '^'

Addressed by: https://review.openstack.org/306022
    clean up versions.inc reference document

Gerrit topic: https://review.openstack.org/#q,topic:api-ref,n,z

Addressed by: https://review.openstack.org/306376
    Collection of CSS fixes

Addressed by: https://review.openstack.org/306595
    Fix "Creates an agent build" parameters

Addressed by: https://review.openstack.org/306607
    Fix "Creates an aggregate" parameters

Addressed by: https://review.openstack.org/306622
    Update servers.inc to be as accurate as api-site

Addressed by: https://review.openstack.org/306652
    Fix "No field definition" warnings (1/2)

Addressed by: https://review.openstack.org/307011
    Fix "Delete a service " return value

Addressed by: https://review.openstack.org/307023
    Add 'binary' and 'disable-reason'

Addressed by: https://review.openstack.org/307043
    rename the response json simple-tenant-usage

Addressed by: https://review.openstack.org/307052
    Fix os-server-groups.inc

Addressed by: https://review.openstack.org/307109
    fix samples references for 2 files

Addressed by: https://review.openstack.org/307137
    Update 'os-hypervisors.inc' in api-ref

Addressed by: https://review.openstack.org/307164
    Fix api samples references in 3 more files

Addressed by: https://review.openstack.org/307424
    Fix hosts and az api samples

Addressed by: https://review.openstack.org/307520
    Remove 40X and 50X from Normal response codes

Addressed by: https://review.openstack.org/307522
    Specify normal status code on os-baremetal-nodes

Addressed by: https://review.openstack.org/307645
    Fix json response example heading in api ref

Addressed by: https://review.openstack.org/307665
    Fix server-action-crash-dump.inc

Addressed by: https://review.openstack.org/307690
    Add remaining image API ref

Addressed by: https://review.openstack.org/307696
    Fix api ref for ips, limits, metdata and agent

Addressed by: https://review.openstack.org/307710
    Fix diagnostics, extensions api ref

Addressed by: https://review.openstack.org/307716
    Fix os-virtual-interfaces and flavors api-ref

Addressed by: https://review.openstack.org/307728
    Fix flavor-access and flavor-extras api-ref

Addressed by: https://review.openstack.org/307743
    Fix wrong link of version and version_min

Addressed by: https://review.openstack.org/307793
    Fix the parameters for os-agents API

Addressed by: https://review.openstack.org/307794
    Fix api ref for os-cells, os-cloudpipe and server-action-shelve

Addressed by: https://review.openstack.org/307812
    Fix api ref for os-hosts, os-quota-sets and os-fping

Addressed by: https://review.openstack.org/307857
    fix samples references in os-services

Addressed by: https://review.openstack.org/307899
    fix samples references in security group files

Addressed by: https://review.openstack.org/307990
    Change adminPass for several server actions

Addressed by: https://review.openstack.org/308104
    Fix sample path for aggregate, certificate, console

Addressed by: https://review.openstack.org/308109
    Fix sample file path for fixed, floating ips API

Addressed by: https://review.openstack.org/308114
    Fix sample file path for os-i* API

Addressed by: https://review.openstack.org/308119
    Fix content and sample file for keypair, migration, networks

Addressed by: https://review.openstack.org/308150
    Fix sample file path for 4 files

Addressed by: https://review.openstack.org/308180
    Fix all remaining sample file path

Addressed by: https://review.openstack.org/308187
    Remove duplicate api ref for os-networks/actions

Addressed by: https://review.openstack.org/308288
    change host to host_migration

Addressed by: https://review.openstack.org/308299
    modify duplicate // to / in doc

Addressed by: https://review.openstack.org/308308
    Fix remaining json reference warnings

Addressed by: https://review.openstack.org/308404
    Final warnings removals for api-ref

Addressed by: https://review.openstack.org/308569
    add tags to files for the content verification phase

Addressed by: https://review.openstack.org/308716
    Add api sample test for non-existed endpoint request

Addressed by: https://review.openstack.org/308720
    Fix the versions API for api-ref

Addressed by: https://review.openstack.org/309568
    Complet Method Verification of server diag

Addressed by: https://review.openstack.org/309578
    Complet Method Verification of limits

Addressed by: https://review.openstack.org/309727
    Add links to API guide to describe links

Addressed by: https://review.openstack.org/310003
    Complet Method Verification of server group

Addressed by: https://review.openstack.org/310012
    Complet Method Verification of os-services

Addressed by: https://review.openstack.org/310186
    Complet Method Verification of simple tenant usage

Addressed by: https://review.openstack.org/310189
    Complet Method Verification of availability-zone

Addressed by: https://review.openstack.org/310196
    Complet Method Verification of keypair

Addressed by: https://review.openstack.org/310391
    Complet Method Verification of flavor

Addressed by: https://review.openstack.org/310401
    Complet Method Verification of flavor-access

Addressed by: https://review.openstack.org/310706
    Complete Verification of os-flavor-extra-specs

Addressed by: https://review.openstack.org/310711
    Complet Method Verification of os-instance-actions

Addressed by: https://review.openstack.org/310716
    Complete Verification of os-virtual-interfaces

Addressed by: https://review.openstack.org/310724
    Complete Method Verification of os-interface

Addressed by: https://review.openstack.org/311070
    Complete Verification of os-floating-ip-pools

Addressed by: https://review.openstack.org/311071
    Complete Verification of os-floating-ips

Addressed by: https://review.openstack.org/311077
    Complete Verification of os-hosts

Addressed by: https://review.openstack.org/311719
    Complete Verification of os-server-password

Addressed by: https://review.openstack.org/311723
    Complete Verification of server-metadata

Addressed by: https://review.openstack.org/311727
    Complete Verification of server admin action

Addressed by: https://review.openstack.org/312024
    Complete method Verification of os-hypervisors

Addressed by: https://review.openstack.org/312029
    Complete method Verification of consoles

Addressed by: https://review.openstack.org/312434
    Complete Method Verification of ips

Addressed by: https://review.openstack.org/312465
    complete Method Verification of aggregates

Addressed by: https://review.openstack.org/313514
    api-ref: method verification and fixes for servers.inc

Addressed by: https://review.openstack.org/313532
    WIP: api-ref: working on parameters validation for servers

Addressed by: https://review.openstack.org/313635
    Complete method verification of os-fixed-ips

Addressed by: https://review.openstack.org/313653
    Complete method verification of os-agents

Addressed by: https://review.openstack.org/313959
    Add api-sample test for showing quota detail

Addressed by: https://review.openstack.org/313960
    Complete method verification of os-quotes

Addressed by: https://review.openstack.org/313961
    Complete method verification of os-shevle

Addressed by: https://review.openstack.org/313966
    Compelete method verification of os-servers-admin

Addressed by: https://review.openstack.org/314085
    api-ref: complete verification for diagnostics.inc

Addressed by: https://review.openstack.org/314101
    api-ref: complete verification for extensions resource

Addressed by: https://review.openstack.org/314133
    WIP: api-ref: flavors

Addressed by: https://review.openstack.org/314139
    Complete method verification of os-tenant-networks

Addressed by: https://review.openstack.org/314198
    [WIP] Complete method verification of os-networks

Addressed by: https://review.openstack.org/314255
    [WIP] Complete method verification of os-security-groups

Addressed by: https://review.openstack.org/314264
    Complete method verification of os-security-group-rules

Addressed by: https://review.openstack.org/314268
    [WIP] api-ref: Update method validation on images

Addressed by: https://review.openstack.org/314271
    api-ref: add url parameter to expand all sections

Addressed by: https://review.openstack.org/314257
    api-ref: perform all 4 phases of verification for action console output

Addressed by: https://review.openstack.org/314287
    Complete method verification of os-fping

Addressed by: https://review.openstack.org/314309
    WIP: api-ref: Verify methods for metadata.inc

Addressed by: https://review.openstack.org/314310
    Complete method verification of os-migrations

Addressed by: https://review.openstack.org/314320
    api-ref: ips.inc parameter verification

Addressed by: https://review.openstack.org/314325
    api-ref: os-volumes.inc method verification

Addressed by: https://review.openstack.org/314328
    WIP: api-ref: ips.inc example verification

Addressed by: https://review.openstack.org/314355
    Remove 404 for list and details action servers

Addressed by: https://review.openstack.org/314502
    WIP: api-ref keypair update

Addressed by: https://review.openstack.org/314521
    Denormalize extensions for clarity

Addressed by: https://review.openstack.org/314566
    api-ref: complete verification of servers-action-crash-dump.inc

Addressed by: https://review.openstack.org/314600
    Denormalize personality extension

Addressed by: https://review.openstack.org/314748
    method verification for servers-action-fixed-ip

Addressed by: https://review.openstack.org/314776
    [WIP] api-ref, evacuate action

Addressed by: https://review.openstack.org/314783
    Complete method verification of os-cloudpipe.inc

Addressed by: https://review.openstack.org/314794
    api-ref: Method verification for os-floating-ips

Addressed by: https://review.openstack.org/314796
    api-ref: os-certificates.inc method verification

Addressed by: https://review.openstack.org/314798
    api-ref: Method verification for floating-ip-pools

Addressed by: https://review.openstack.org/314802
    method verification of os-assisted-volume-snapshots

Addressed by: https://review.openstack.org/314833
    api-ref: parameter and example verification for os-quota-sets

Addressed by: https://review.openstack.org/314924
    WIP: api-ref host verification (os-hosts.inc)

Addressed by: https://review.openstack.org/315100
    method verification for server-action-remote-consoles

Addressed by: https://review.openstack.org/315126
    api-ref: parameter validation for os-security-group-rules

Addressed by: https://review.openstack.org/315127
    [WIP] Complete method verification of os-baremetal-nodes.inc

Addressed by: https://review.openstack.org/315145
    Method verification for server deferred delete

Addressed by: https://review.openstack.org/315170
    method verification of os-instance-usage-audit-log

Addressed by: https://review.openstack.org/315182
    method verification of os-server-external-events

Addressed by: https://review.openstack.org/315199
    Method verification of os-floating-ips-bulk.inc

Addressed by: https://review.openstack.org/315212
    api-ref: finish validation for os-server-external-events.inc

Addressed by: https://review.openstack.org/315216
    WIP: api-ref: limits.inc validate parameters

Addressed by: https://review.openstack.org/315220
    api-ref: Method verification for servers-actions

Addressed by: https://review.openstack.org/315252
    WIP: api-ref: ips.inc example verification

Addressed by: https://review.openstack.org/315257
    Method verification of os-security-group-default-rules

Addressed by: https://review.openstack.org/315284
    [WIP]api-ref: os-floating-ip-dns.inc method verification

Addressed by: https://review.openstack.org/315289
    api-ref: Method verification for os-volume_attachments.inc

Addressed by: https://review.openstack.org/315318
    api-ref: Parameter verification for os-interface.inc

Addressed by: https://review.openstack.org/315394
    api-ref: parameter verification for os-server-groups

Addressed by: https://review.openstack.org/315517
    WIP api-ref: parameter verification for os-aggregates

Addressed by: https://review.openstack.org/315592
    report info if parameters are out of order

Addressed by: https://review.openstack.org/315617
    api-ref: reorder parameters.yaml

Addressed by: https://review.openstack.org/315714
    WIP: limits.inc example verification

Addressed by: https://review.openstack.org/315877
    api-ref: Parameter verification for os-volume_attachments.inc

Addressed by: https://review.openstack.org/315895
    api-ref: Example verification for os-volume_attachments.inc

Addressed by: https://review.openstack.org/315934
    api-ref: Example verification for os-interface.inc

Addressed by: https://review.openstack.org/316681
    api-ref: parameter verification for os-hypervisors

Addressed by: https://review.openstack.org/316972
    WIP: api-ref: complete verification for os-flavor-access

Addressed by: https://review.openstack.org/317622
    Trivial: remove os-security-groups needs:method_verification line

Gerrit topic: https://review.openstack.org/#q,topic:api-ref-os-consoles,n,z

Addressed by: https://review.openstack.org/317536
    api-ref: os-consoles.inc

Addressed by: https://review.openstack.org/317803
    api-ref: Fix parameters in servers-action-shelve.inc

Addressed by: https://review.openstack.org/317836
    api-ref: Example verification for servers-action-shelve.inc

Addressed by: https://review.openstack.org/317955
    api-ref: Add fault parameter details

Addressed by: https://review.openstack.org/317992
    api-ref verify servers-action-deferred-delete.inc

Addressed by: https://review.openstack.org/317994
    verify api-ref os-server-password.inc

Addressed by: https://review.openstack.org/317998
    verify api-ref os-instance-usage-audit-log.inc

Addressed by: https://review.openstack.org/318004
    verify api-ref os-migrations.inc

Addressed by: https://review.openstack.org/318295
    api-ref: complete verification of baremetal api

Addressed by: https://review.openstack.org/318600
    verify api-ref metadata.inc

Addressed by: https://review.openstack.org/318764
    api-ref, os-fping.inc

Addressed by: https://review.openstack.org/321784
    WIP: api-ref method verification for os-cells

Addressed by: https://review.openstack.org/321847
    [WIP] api-ref, os-availability-zone.inc

Addressed by: https://review.openstack.org/321956
    api-ref: Add a sample test for os-interface

Addressed by: https://review.openstack.org/325269
    api-ref: verify os-server-groups.inc

Addressed by: https://review.openstack.org/325276
    api-ref: verify os-certificates

Addressed by: https://review.openstack.org/325308
    api-ref: verify keypairs

Addressed by: https://review.openstack.org/325502
    api-ref: add version 2.3 parameters to servers

Addressed by: https://review.openstack.org/325896
    api-ref: body verification of ips.inc

Addressed by: https://review.openstack.org/325899
    api-ref: verfiy limits body

Addressed by: https://review.openstack.org/326120
    api-ref: parameter verification os-fixed-ips

Addressed by: https://review.openstack.org/326871
    api-ref: verify images.inc

Addressed by: https://review.openstack.org/326975
    api-ref: verify assisted-volume-snapshots.inc

Gerrit topic: https://review.openstack.org/#q,topic:bp/tag-instances,n,z

Addressed by: https://review.openstack.org/327089
    api-ref: added docs for microversion 2.26

Addressed by: https://review.openstack.org/328981
    api-ref: Fix parameters in os-instance-usage-audit-log

Addressed by: https://review.openstack.org/326116
    api-ref: parameter verification os-agents

Addressed by: https://review.openstack.org/326117
    api-ref: parameter verification os-security-groups

Addressed by: https://review.openstack.org/329704
    api-ref example verification for os-floating-ips

Addressed by: https://review.openstack.org/320048
    api-ref: os-volumes.inc

Gerrit topic: https://review.openstack.org/#q,topic:bp/nova-api-hypervsor-cpu-info,n,z

Addressed by: https://review.openstack.org/331747
    api-ref: docs for microversion v2.28

Addressed by: https://review.openstack.org/332089
    api-ref: Improve os-instance_usage_audit_log samples

Addressed by: https://review.openstack.org/321123
    api-ref, os-services.inc

Addressed by: https://review.openstack.org/333075
    Complete verification for os-floating-ips-bulk

Addressed by: https://review.openstack.org/333114
    Verify os-aggregates.inc on sample files

Addressed by: https://review.openstack.org/333156
    Add multiple create in document

Addressed by: https://review.openstack.org/333378
    api-ref: merge multiple create to servers.inc

Addressed by: https://review.openstack.org/333538
    api-ref: add not about os-certificates API

Addressed by: https://review.openstack.org/333651
    Complete verification for api-ref os-flavor-extra-specs

Addressed by: https://review.openstack.org/333654
    api-ref: Parameter verification for os-simple-tenant-usage.inc

Gerrit topic: https://review.openstack.org/#q,topic:bug/1587070,n,z

Addressed by: https://review.openstack.org/327112
    WIP api-ref: Checking the parameters of servers-actions.inc

Addressed by: https://review.openstack.org/334353
    api-ref: correct the order of APIs in server-tags

Addressed by: https://review.openstack.org/334453
    api-ref: Example verification for os-agents.inc

Addressed by: https://review.openstack.org/323365
    api-ref: os-certificates.inc

Addressed by: https://review.openstack.org/335678
    Example verification for os-fixed-ips.inc

Addressed by: https://review.openstack.org/335702
    Complete verification for os-virtual-interfaces

Addressed by: https://review.openstack.org/336334
    Body Verification of api-ref os-volume-attachments.inc

Gerrit topic: https://review.openstack.org/#q,topic:bp/keypairs-pagination,n,z

Addressed by: https://review.openstack.org/336546
    api-ref: docs for microversion v2.34

Addressed by: https://review.openstack.org/337125
    api-ref: Example verification for os-simple-tenant-usage.inc

Addressed by: https://review.openstack.org/337996
    Parameter verification of os-instance-actions.inc

Addressed by: https://review.openstack.org/338037
    api-ref: Parameter verification for servers-actions.inc

Addressed by: https://review.openstack.org/338038
    api-ref: Example verification for servers-actions.inc

Addressed by: https://review.openstack.org/338039
    api-ref: Body verification for servers-actions.inc

Addressed by: https://review.openstack.org/338044
    api-ref: Example verification for servers.inc

Addressed by: https://review.openstack.org/338045
    api-ref: Body verification for servers.inc

Addressed by: https://review.openstack.org/338051
    api-ref: Complete all the verifications of remote consoles

Addressed by: https://review.openstack.org/338053
    api-ref: Body verification for os-hypervisor.inc

Addressed by: https://review.openstack.org/338055
    api-ref: example verification for os-hypervisors.inc

Addressed by: https://review.openstack.org/338115
    Body verification of os-interface.inc

Addressed by: https://review.openstack.org/338126
    api-ref: Parameter verification for servers-actions.inc Part 1

Addressed by: https://review.openstack.org/338140
    Example and body verification of os-quota-sets.inc

Addressed by: https://review.openstack.org/338606
    Complete verification of servers-action-fixed-ip.inc

Addressed by: https://review.openstack.org/338651
    api-ref: unify the delete response infomation

Addressed by: https://review.openstack.org/338705
    api-ref: body verification of os-agents

Addressed by: https://review.openstack.org/338753
    Complete verification of os-instance-actions.inc

Addressed by: https://review.openstack.org/339315
    Parameter verification of os-floating-ip-dns.inc

Addressed by: https://review.openstack.org/339327
    api-ref: fix wrong description about response example in os-hypervisor

Addressed by: https://review.openstack.org/339328
    api-ref: add sample file link for different microversion in hypervisors

Addressed by: https://review.openstack.org/339335
    Verify os-floating-ip-dns.inc on sample files

Addressed by: https://review.openstack.org/339336
    api-ref: Body verification for os-simple-tenant-usage.inc

Addressed by: https://review.openstack.org/346641
    api-ref: unify the no response output in delete operation

Addressed by: https://review.openstack.org/353435
    [WIP] Complete verification of os-aggregates.inc

Addressed by: https://review.openstack.org/355099
    Change hypervisor_type to actual value

Addressed by: https://review.openstack.org/356163
    Change api-site to v2.1 format

Addressed by: https://review.openstack.org/366023
    Body Verification of os-aggregates.inc

Addressed by: https://review.openstack.org/366681
    Example & Parameter verification of os-security-group-default-rules.inc

Addressed by: https://review.openstack.org/369054
    Fix server group name on api-ref

Addressed by: https://review.openstack.org/369055
    Fix the name of DNS entry on api-ref

Addressed by: https://review.openstack.org/369058
    Fix server name on api-ref

Addressed by: https://review.openstack.org/369059
    Rename 'name' to 'secgroup_name' in api-ref

Addressed by: https://review.openstack.org/369135
    Correct sort_key and sort_dir parameter for flavor

Addressed by: https://review.openstack.org/369141
    Correct image.inc for heading and ordering

Addressed by: https://review.openstack.org/369148
    Correct address parameter for server IP API

Addressed by: https://review.openstack.org/369161
    Fix order of Create and Show method in os-aggregates.inc

Addressed by: https://review.openstack.org/369182
    Complete verification for os-cloudpipe.inc

Addressed by: https://review.openstack.org/370732
    Add hypervisor_links into hypervisor

Addressed by: https://review.openstack.org/370740
    Trivial fix remove not used var in parameters

Addressed by: https://review.openstack.org/370760
    Add keypairs_links into resp

Addressed by: https://review.openstack.org/370770
    fix broken link in api-ref

Let's consider this closed for newton. I've created a follow up blueprint for ocata here:

https://blueprints.launchpad.net/nova/+spec/api-ref-in-rst-ocata

-- mriedem 20160915

Gerrit topic: https://review.openstack.org/#q,topic:bp/api-ref-in-rst-ocata,n,z

Addressed by: https://review.openstack.org/383683
    api-ref: Body verification for os-simple-tenant-usage.inc

Addressed by: https://review.openstack.org/456053
    api-ref: Fix examples for add/removeFixedIp action

(?)

Work Items

Dependency tree

* Blueprints in grey have been implemented.

This blueprint contains Public information 
Everyone can see this information.