Error name and description aren't getting imported from XSD files

[annegentle]

When migrating the Compute WADLs, the response code tables look like this:

+--------------------------+-------------------------+-------------------------+
|Response Code             |Name                     |Description              |
+==========================+=========================+=========================+
|200                       |                         |                         |
+--------------------------+-------------------------+-------------------------+

I would expect the Name and Description to come from the content. In WADL I believe those are referenced from the XSD files.

[annegentle]

I think that this additional is required in the WADL and the WADLs would have to be updated to include this. I believe the use of the entity reference is causing this for common faults especially. Those are encoded as such:

<response>
               <representation mediaType="application/xml" element="csapi:computeFault"/>
               <representation mediaType="application/json"/>
            </response>
            <response status="503">
               <representation mediaType="application/xml" element="csapi:serviceUnavailable"/>
               <representation mediaType="application/json"/>
            </response>
            <response status="400">
               <representation mediaType="application/xml" element="csapi:badRequest"/>
               <representation mediaType="application/json"/>
            </response>

However, the <doc title=""> example below is what the wadl2rst tool can render/parse.

<response status="202">
            <doc title="Success">Request succeeded.</doc>
            <representation mediaType="application/json">
                <wadl:doc xml:lang="en">
                    <xsdxt:code href="../common/samples/server-create-rsp-json-http.txt"/>
                    <xsdxt:code href="../common/samples/server-create-rsp.json"/>
                </wadl:doc>&serverCreateRspParameters;
            </representation>
        </response>&commonFaults; </method>```

[annegentle]

Rather than outputting tables, our idea is actually this:

2 li items

• Success: ....
• Errors Codes: ....

[annegentle]

Okay, here's my idea. This is the input from a "flattened" WADL, which is what wadl2rst works on:

    <response>
       <representation mediaType="application/xml" element="csapi:computeFault"/>
       <representation mediaType="application/json"/>
    </response>
    <response status="503">
       <representation mediaType="application/xml" element="csapi:serviceUnavailable"/>
       <representation mediaType="application/json"/>
    </response>
    <response status="400">
       <representation mediaType="application/xml" element="csapi:badRequest"/>
       <representation mediaType="application/json"/>
    </response>
    <response status="401">
       <representation mediaType="application/xml" element="csapi:unauthorized"/>
       <representation mediaType="application/json"/>
    </response>
    <response status="403">
       <representation mediaType="application/xml" element="csapi:forbidden"/>
       <representation mediaType="application/json"/>
    </response>
    <response status="405">
       <representation mediaType="application/xml" element="csapi:badMethod"/>
       <representation mediaType="application/json"/>
    </response>```

Currently, the code isn't getting the info from a `faults.xsd` file to fill in the text for `element="csapi:badMethod"` for example, and instead is looking for the title in the example pasted way above.

So, I think what the `nodes/method.py` code should do instead of outputting a table is to output a list of possible Success codes and possible Error codes. I can make a list of the the text for each, and the status="400" for example would need to match up to the text from `faults.xsd`. I'm not completely sure of the coding needed, though.

Here are the status codes from `faults.xsd`.

`<element name="computeFault" type="csapi:ComputeAPIFault">
    <annotation>
      <xsd:documentation xml:lang="EN"
        xmlns="http://www.w3.org/1999/xhtml">
        <p>A generic Cloud Servers API fault.</p>
      </xsd:documentation>
    </annotation>
  </element>
  <element name="itemNotFound" type="csapi:ItemNotFoundAPIFault">
    <annotation>
      <xsd:documentation xml:lang="EN"
        xmlns="http://www.w3.org/1999/xhtml">
        <p>The item or resource could not be found.</p>
      </xsd:documentation>
    </annotation>
  </element>
  <element name="buildInProgress" type="csapi:BuildInProgressAPIFault">
    <annotation>
      <xsd:documentation xml:lang="EN"
        xmlns="http://www.w3.org/1999/xhtml">
        <p>The operation is not allowed because the corresponding
          server is in a build state.</p>
      </xsd:documentation>
    </annotation>
  </element>
  <element name="serverCapacityUnavailable"
    type="csapi:ServerCapacityUnavailableAPIFault">
    <annotation>
      <xsd:documentation xml:lang="EN"
        xmlns="http://www.w3.org/1999/xhtml">
        <p>There is not enough capacity to honor the request.</p>
      </xsd:documentation>
    </annotation>
  </element>
  <element name="backupOrResizeInProgress"
    type="csapi:BackupOrResizeInProgressAPIFault">
    <annotation>
      <xsd:documentation xml:lang="EN"
        xmlns="http://www.w3.org/1999/xhtml">
        <p>The operation is not allowed because the corresponding
          server is being re-sized or backed up.</p>
      </xsd:documentation>
    </annotation>
  </element>
  <element name="serviceUnavailable"
    type="csapi:ServiceUnavailableAPIFault">
    <annotation>
      <xsd:documentation xml:lang="EN"
        xmlns="http://www.w3.org/1999/xhtml">
        <p>The API service is currently unavailable.</p>
      </xsd:documentation>
    </annotation>
  </element>
  <element name="unauthorized" type="csapi:UnauthorizedAPIFault">
    <annotation>
      <xsd:documentation xml:lang="EN"
        xmlns="http://www.w3.org/1999/xhtml">
        <p>Insufficient privileges to honor the request, perhaps an
          authentication token needs to be obtained or renewed.</p>
      </xsd:documentation>
    </annotation>
  </element>
  <element name="forbidden" type="csapi:ForbiddenAPIFault">
    <annotation>
      <xsd:documentation xml:lang="EN"
        xmlns="http://www.w3.org/1999/xhtml">
        <p>Authentication has been validated, however the operation is
          unauthorized.</p>
      </xsd:documentation>
    </annotation>
  </element>
  <element name="overLimit" type="csapi:OverLimitAPIFault">
    <annotation>
      <xsd:documentation xml:lang="EN"
        xmlns="http://www.w3.org/1999/xhtml">
        <p>An <a href="limits.xsd#type_AbsoluteLimit"
            title="See
          definition of AbsoluteLimit"
            >absolute</a> or <a href="limits.xsd#type_RateLimit"
            title="See definition of
          RateLimit">rate</a>
          limit has been exceeded.</p>
      </xsd:documentation>
    </annotation>
  </element>
  <element name="badRequest" type="csapi:BadRequestAPIFault">
    <annotation>
      <xsd:documentation xml:lang="EN"
        xmlns="http://www.w3.org/1999/xhtml">
        <p>The request is malformed.</p>
      </xsd:documentation>
    </annotation>
  </element>
  <element name="badMediaType" type="csapi:BadMediaTypeAPIFault">
    <annotation>
      <xsd:documentation xml:lang="EN"
        xmlns="http://www.w3.org/1999/xhtml">
        <p>The Content Type of the request is not supported.</p>
      </xsd:documentation>
    </annotation>
  </element>
  <element name="badMethod" type="csapi:BadMethodAPIFault">
    <annotation>
      <xsd:documentation xml:lang="EN"
        xmlns="http://www.w3.org/1999/xhtml">
        <p>The HTTP method (or <a href="limits.xsd#type_HTTPVerb"
            title="See definition of HTTPVerb">verb</a>) is not
          supported by the corresponding resource.</p>
      </xsd:documentation>
    </annotation>
  </element>
  <element name="notImplemented" type="csapi:NotImplementedAPIFault">
    <annotation>
      <xsd:documentation xml:lang="EN"
        xmlns="http://www.w3.org/1999/xhtml">
        <p>The operation is currently not implemented.</p>
      </xsd:documentation>
    </annotation>
  </element>
  <!-- Complex Types -->
  <complexType name="ComputeAPIFault">
    <sequence>
      <element name="message" type="xsd:string">
        <annotation>
          <xsd:documentation xml:lang="EN"
            xmlns="http://www.w3.org/1999/xhtml">
            <p>A human readable message that is appropriate for
              display to the end user.</p>
          </xsd:documentation>
        </annotation>
      </element>
      <element name="details" type="xsd:string" minOccurs="0">
        <annotation>
          <xsd:documentation xml:lang="EN"
            xmlns="http://www.w3.org/1999/xhtml">
            <p>The optional &lt;details&gt; element might contain
              useful information for tracking down errors, such as a
              stack trace. This information might or might not be
              appropriate for display to an end user.</p>
          </xsd:documentation>
        </annotation>
      </element>`

[annegentle]

Actually, here's a screenshot of the ideal output, at the bottom of a page (not in its current location).

[missaugustina]

I'm a little confused why we need to hard code the faults.xsd content into wadl2rst? It seems like this is a bigger pipeline issue if that content isn't getting properly inserted into the api-site docs. Or does something else in the api-site pipeline eventually include the faults.xsd which is why it's not in the wadl? If so, then rather than hard-code that content, we should probably read it in, reference it, and consolidate it in the errors method you're proposing.

If those xsd files represent common global text, it probably makes sense for us to add something to this codebase for processing those files and creating data structures that can be referenced when building the rst output.

[missaugustina]

For reference, this is the xsd file: https://github.com/openstack/api-site/blob/master/api-ref/src/wadls/compute-api/src/v2.1/xsd/faults.xsd

[annegentle]

Yep, I'm not sure myself why the text from faults.xsd isn't being brought in. If you want to see how the api-site/api-ref docs are made, it's XSLT in https://github.com/openstack/clouddocs-maven-plugin/blob/e3e83382783aa4c6bc5b83630c5c5a184394811b/src/main/resources/cloud/apipage/apipage-main.xsl#L740

[missaugustina]

We came up with a solution for the first pass, but we should revisit this if we decide to do further work here.

[annegentle]

Sounds good.

[annegentle]

Closing issue -- I believe we have a new solution in a Sphinx extension.