Merge pull request #694 from mDuo13/xrp-api-ref

Add XRP-API Reference (Auto-generated)

dactyl-config.yml

@@ -50,19 +50,12 @@ targets:
         #  Override them with --vars to change which fork/branch to edit.
         github_forkurl: https://github.com/ripple/xrpl-dev-portal
         github_branch: master
-        recently_updated:
-            - html: rippleapi-reference.html
-              date: 2019-09-10
-            - html: look-up-transaction-results.html
-              date: 2019-05-02
-            - html: tx-sender.html
-              date: 2019-05-01
-            - html: transaction-metadata.html
-              date: 2019-04-25
-            - html: open-a-payment-channel-to-enable-an-inter-exchange-network.html
-              date: 2019-03-22
-            - html: set-up-secure-signing.html
-              date: 2019-03-13
+
+    -   name: xrp-api-only
+        display_name: XRP API Reference
+        github_forkurl: https://github.com/ripple/xrpl-dev-portal
+        github_branch: master
+        no_cover: true
 
     # Data API target for porting changes to the README in the upstream repo
     # Intended for use in markdown (--md) mode.
@@ -2324,7 +2317,7 @@ pages:
         supercategory: rippled API
         category: Ledger Data Formats
         subcategory: Ledger Object Types
-        template: template-landing-children.html #TODO: consider dropping the md since the page children handles this OK
+        template: template-landing-children.html
         blurb: Each ledger's state tree consists of a set of ledger objects, which collectively represent all settings, balances, and relationships in the shared ledger. In the peer protocol that rippled servers use to communicate with each other, ledger objects are represented in their raw binary format. In the rippled API, ledger objects are represented as JSON objects.
         targets:
             - local
@@ -2837,7 +2830,31 @@ pages:
         targets:
             - local
 
-    # --------------- end "rippled API" section --------------------------------
+    # XRP-API docs (auto-generated)---------------------------------------------
+
+    -   name: XRP-API
+        md: https://raw.githubusercontent.com/ripple/xrp-api/master/README.md
+        html: xrp-api.html
+        funnel: Docs
+        doc_type: References
+        supercategory: XRP-API
+        targets:
+            - local
+            - xrp-api-only
+
+        # API reference generator makes multiple files here
+    -   openapi_specification: https://raw.githubusercontent.com/ripple/xrp-api/master/api-doc.yml
+        openapi_md_template_path: tool/openapi_templates_alpha/
+        api_slug: xrp-api
+        funnel: Docs
+        doc_type: References
+        supercategory: XRP-API
+        targets:
+            - local
+            - xrp-api-only
+
+
+    # --------------- end "XRP-API" section --------------------------------
 
     -   name: RippleAPI Reference # name is required for remote-sourced files
         md: https://raw.githubusercontent.com/ripple/ripple-lib/1.3.3/docs/index.md

tool/openapi_templates_alpha/template-openapi_data_type.md

@@ -0,0 +1,64 @@
+# {{title}}
+
+{{description}}
+
+**Warning:** {{spec.info.title}} is early alpha software. API methods and data formats are likely to change frequently in ways that break backwards compatibility.
+
+{% if type is defined %}- **Type:** {{type|title}}
+{% elif oneOf is defined %}- **Possible Types:**
+{% for option in oneOf -%}
+{% if option.enum is defined %}
+    - One of the following {% if option.type is defined %}{{option.type|title}}s{% else %}values{% endif %}:
+{% for suboption in option.enum %}
+        - `{{suboption}}`
+{% endfor -%}
+{% else %}
+    - {{option.type|title}}
+{% endif -%}
+{% endfor -%}
+{% elif anyOf is defined %}- **Possible Types:**
+{% for option in anyOf -%}
+{% if option.enum is defined %}
+    - Any of the following {% if option.type is defined %}{{option.type|title}}s{% else %}values{% endif %}:
+{% for suboption in option.enum %}
+        - `{{suboption}}`
+{% endfor -%}
+{% else %}
+    - {{option.type|title}}
+{% endif -%}
+{% endfor -%}
+{% elif allOf is defined %}- **Possible Types:**
+{% for option in allOf -%}
+{% if option.enum is defined %}
+    - Must qualify as all of the following {% if option.type is defined %}{{option.type|title}}s{% else %}values{% endif %}:
+{% for suboption in option.enum %}
+        - `{{suboption}}`
+{% endfor -%}
+{% else %}
+    - {{option.type|title}}
+{% endif -%}
+{% endfor -%}
+{% endif -%}
+{% if enum is defined %}- **Possible Values:**
+{% for option in enum %}
+    - `{{option}}`
+{% endfor %}{% endif %}
+{% if pattern is defined %}- **Pattern:** `{{pattern}}`
+{% endif -%}
+{% if example is defined %}- **Example:** `{{example}}`
+{% endif -%}
+
+{% if properties is defined %}
+This type can contain the following fields:
+
+| Field | Type | Required? | Description |
+|-------|------|-----------|-------------|
+{%- for name,field in properties.items() %}
+| `{{name}}` | {{field.type|title}}{% if "items" in field.keys() and "title" in field["items"].keys() %} of [{{field["items"].title}}]({{type_link(field["items"].title)}}){% endif %} {% if field["title"] is defined %}([{{field.title}}]({{type_link(field.title)}})){% endif %} | {{"Required" if name in required else "Optional"}} | {{field.description}} |
+{%- endfor %}
+
+{% if additionalProperties is defined and additionalProperties == True %}This type MUST NOT contain any additional fields.{% endif %}
+
+{% elif type == "array" and items is defined %}
+Each member of the array is a ***TODO*** {{items}}
+{% endif %}

tool/openapi_templates_alpha/template-openapi_data_types_toc.md

@@ -0,0 +1,11 @@
+# {{api_title}} Data Types
+
+**Warning:** {{spec.info.title}} is early alpha software. API methods and data formats are likely to change frequently in ways that break backwards compatibility.
+
+The following data types are defined for this API:
+
+| Name | Type | Description |
+|------|------|-------------|
+{%- for key,schema in schemas %}
+| `{{schema.title}}` | {{schema.type|title}}{% if "items" in schema.keys() and "title" in schema["items"].keys() %} of [{{schema["items"].title}}]({{type_link(schema["items"].title)}}){% endif %} {% if schema["title"] is defined %}([{{schema.title}}]({{type_link(schema.title)}})){% endif %} | {% if schema.description is defined %}{{schema.description}}{% endif %} |
+{%- endfor %}

tool/openapi_templates_alpha/template-openapi_endpoint.md

@@ -0,0 +1,107 @@
+# {{summary}}
+
+{{description}}
+
+**Warning:** {{spec.info.title}} is early alpha software. API methods and data formats are likely to change frequently in ways that break backwards compatibility.
+
+## Request Format
+
+```
+{{method|upper}} {{path}}
+{%- if method in ["post","put","delete"] and requestBody is defined %}
+
+{{ x_example_request_body }}
+{% endif %}
+```
+
+{% if path_params|length %}
+This API method uses the following path parameters:
+
+| Field | Value | Required? | Description |
+|---|---|---|---|
+{%- for param in path_params %}
+| `{{param.name}}` | {% if param.schema is defined %}{% if param.schema.oneOf is defined %}(Varies){% else %}{{param.schema.type|title}}{% endif %} {% if param.schema["title"] is defined %}([{{param.schema.title}}]({{type_link(param.schema.title)}})){% endif %}{% else %}(Unspecified){% endif %} | {{"Required" if param.required else "Optional"}} | {{param.description}} |
+{%- endfor %}
+
+{% endif %}
+
+{% if query_params|length %}
+This API method uses the following query parameters:
+
+| Field | Value | Required? | Description |
+|---|---|---|---|
+{%- for param in query_params %}
+| `{{param.name}}` | {% if param.schema is defined %}{% if param.schema.oneOf is defined %}(Varies){% else %}{{param.schema.type|title}}{% if "items" in param.schema.keys() and "title" in param.schema["items"].keys() %} of [{{param.schema["items"].title}}]({{type_link(param.schema["items"].title)}}){% endif %}{% endif %} {% if param.schema["title"] is defined %}([{{param.schema.title}}]({{type_link(param.schema.title)}})){% endif %}{% else %}(Unspecified){% endif %} | {{"Required" if param.required else "Optional"}} | {{param.description}} |
+{%- endfor %}
+
+{% endif %}
+
+{% if requestBody is defined %}
+{{requestBody.description}}
+
+{% if requestBody.content is defined %}
+
+{% for mediatype,thisbody in requestBody.content.items() %}
+{% if thisbody.schema is defined %}
+**Media type:** {{mediatype|replace("*","\*")}}
+
+{% if thisbody.schema.title is defined %}
+Formatted as a [{{thisbody.schema.title}}]({{type_link(thisbody.schema.title)}})
+{% endif %}
+{% if thisbody.schema.properties is defined %}
+The request uses the following fields:
+
+| Field | Type | Required? | Description |
+|-------|------|-----------|-------------|
+{%- for name,field in thisbody.schema.properties.items() %}
+| `{{name}}` | {{field.type|title}}{% if "items" in field.keys() and "title" in field["items"].keys() %} of [{{field["items"].title}}]({{type_link(field["items"].title)}}){% endif %} {% if field["title"] is defined %}([{{field.title}}]({{type_link(field.title)}})){% endif %} | {{"Required" if name in required else "May be omitted"}} | {% if field.description is defined %}{{field.description}}{% endif %} |
+{%- endfor %}
+{% endif %}
+
+{% endif %}
+{% endfor %}
+{% endif %}
+{% endif %}
+
+## Response Formats
+
+{% for response_code, response in responses.items() %}
+### {{response_code}} {{HTTP_STATUS_CODES[response_code]}}
+
+{{ response.description}}
+
+{% if response.content is defined %}
+{% for mediatype,thisbody in response.content.items() %}
+{% if thisbody.schema is defined %}
+**Media type:** {{mediatype|replace("*","\*")}}
+
+{% if thisbody.schema.title is defined %}
+Formatted as a [{{thisbody.schema.title}}]({{type_link(thisbody.schema.title)}})
+{% endif %}
+{% if thisbody.schema.properties is defined %}
+The response uses the following fields:
+
+| Field | Type | Required? | Description |
+|-------|------|-----------|-------------|
+{%- for name,field in thisbody.schema.properties.items() %}
+| `{{name}}` | {{field.type|title}}{% if "items" in field.keys() and "title" in field["items"].keys() %} of [{{field["items"].title}}]({{type_link(field["items"].title)}}){% endif %} {% if field["title"] is defined %}([{{field.title}}]({{type_link(field.title)}})){% endif %} | {{"Required" if name in required else "May be omitted"}} | {% if field.description is defined %}{{field.description}}{% endif %} |
+{%- endfor %}
+{% endif %}{# TODO: handle allOf, etc. #}
+
+{% if thisbody.examples is defined and thisbody.examples|length > 0 %}
+#### Example Response(s)
+
+{% for body_name,body_sample in thisbody.examples %}
+_{{body_name}}_
+
+```
+{{body_sample|pprint}}
+```
+{% endfor %}
+{% endif %}
+
+{% endif %}
+{% endfor %}
+
+{% endif %}
+{% endfor %}

tool/openapi_templates_alpha/template-openapi_endpoint_tag_toc.md

@@ -0,0 +1,17 @@
+# {{info.title}} {{info.version}} {{tag.name|title}} Methods
+
+{{tag.description}}
+
+**Warning:** {{info.title}} is early alpha software. API methods and data formats are likely to change frequently in ways that break backwards compatibility.
+
+| Summary | Path |
+|:--------|:-----|
+{%- set reflinks = [] -%}
+{%- for path,method,endpoint in endpoints_by_tag(tag.name) %}
+{%- set _ = reflinks.append("["+endpoint.summary+"]: "+method_link(path, method, endpoint) ) %}
+| [{{endpoint.summary}}][] | [`{{method|upper}} {{path}}`][{{endpoint.summary}}] |
+{%- endfor %}
+
+{% for reflink in reflinks -%}
+{{reflink}}
+{% endfor %}

tool/openapi_templates_alpha/template-openapi_endpoint_toc.md

@@ -0,0 +1,51 @@
+# {{info.title}} {{info.version}} Methods
+
+{{info.description}}
+
+**Warning:** {{spec.info.title}} is early alpha software. API methods and data formats are likely to change frequently in ways that break backwards compatibility.
+
+{% if tags %}
+View API methods by category:
+
+{% for tag in tags %}
+- [{{tag.name|title}} Methods](#{{slugify(tag.name)|lower}}-methods)
+{% endfor %}
+{% endif %}
+
+{% for tag in tags %}
+{% if endpoints_by_tag(tag.name)|list|length %}
+## {{tag.name|title}} Methods
+
+{{tag.description}}
+
+| Summary | Path |
+|:--------|:-----|
+{%- set reflinks = [] -%}
+{%- for path,method,endpoint in endpoints_by_tag(tag.name) %}
+{%- set _ = reflinks.append("["+endpoint.summary+"]: "+method_link(path, method, endpoint) ) %}
+| [{{endpoint.summary}}][] | [`{{method|upper}} {{path}}`][{{endpoint.summary}}] |
+{%- endfor %}
+
+{% for reflink in reflinks -%}
+{{reflink}}
+{% endfor %}
+
+{% endif %}
+{% endfor %}
+
+{% if endpoints_by_tag("Uncategorized")|list|length %}
+## Uncategorized Methods
+
+| Name | Path | Summary |
+|:-----|:-----|:--------|
+{%- set reflinks = [] -%}
+{%- for path,method,endpoint in endpoints_by_tag("Uncategorized") %}
+{%- set _ = reflinks.append("["+endpoint.operationId+"]: "+method_link(path, method, endpoint) ) %}
+| [{{endpoint.operationId}}][] | [`{{method|upper}} {{path}}`][{{endpoint.operationId}}] | {{endpoint.summary}} |
+{%- endfor %}
+
+{% for reflink in reflinks -%}
+{{reflink}}
+{% endfor %}
+
+{% endif %}

tool/template-forpdf.html

@@ -5,7 +5,7 @@
     <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
     <meta name="viewport" content="width=device-width">
 
-    <title>{{ currentpage.name }} - Ripple Developer Portal</title>
+    <title>{{ currentpage.name }} - XRP Ledger Dev Portal</title>
 
     <!-- favicon -->
     <link rel="icon" href="favicon.ico" type="image/x-icon">
@@ -14,13 +14,10 @@
     <!-- jQuery -->
     <script src="assets/vendor/jquery-1.11.1.min.js"></script>
 
-    <!-- Custom Stylesheets. ripple.css includes bootstrap, font stuff -->
-    <link href="assets/css/ripple.css" rel="stylesheet" />
+    <!-- Stylesheet -->
     <link href="assets/css/devportal.css" rel="stylesheet" />
     <link href="assets/css/pdf.css" rel="stylesheet" />
 
-    <!-- Bootstrap JS -->
-    <script src="assets/vendor/bootstrap.min.js"></script>
 
     <!-- syntax highlighting -->
     <link rel="stylesheet" href="assets/vendor/docco.min.css">
@@ -37,15 +34,23 @@
 
 </head>
 
-<body class="page page-template page-template-template-dev-portal page-template-template-dev-portal-php wpb-js-composer js-comp-ver-3.6.2 vc_responsive">
+<body class="xrp-ledger-dev-portal {% if currentpage.sidebar is undefined or currentpage.sidebar != "disabled" %}sidebar-primary {% endif %}{% block bodyclasses %}{% endblock %}">
 
-    <div class='wrapper'>
-    <main class="main" role="main">
-        {{ content }}
-    </main>
+    <div class="container-fluid" role="document" id="main_content_wrapper">
+      <div class="row">
+        <main class="main {% if currentpage.sidebar is defined and currentpage.sidebar == "disabled" %}col-md-12{% else %}col-md-7 col-lg-6{% endif %} order-md-3  {% block mainclasses %}{% endblock %}" role="main" id="main_content_body">
+            {{ content }}
+        </main>
+      </div>
     </div>
 
     <footer>(Exported {{ current_time }})</footer>
 
+<!-- Non-blocking resources -->
+<!-- Bootstrap JS -->
+<script src="assets/vendor/bootstrap.min.js"></script>
+<!-- fontawesome icons -->
+<link rel="stylesheet" href="assets/vendor/fontawesome/css/font-awesome.min.css" />
+
 </body>
 </html>

tool/template-github-edit.html

@@ -1,26 +1,28 @@
 <div class="github-edit-wrap">
-  {% set have_edit_link = False %}
-  {% if currentpage.md is defined %}
-      {% if currentpage.md.startswith("http://") or
-        currentpage.md.startswith("https://") %}
-        {# Leave have_edit_link = False #}
-      {% else %}
-        {% set have_edit_link = True %}
-        {% set githuburl = target.github_forkurl + "/edit/"
-          + target.github_branch
-          + "/content/" + currentpage.md %}
-      {% endif %}
-  {% elif currentpage.template is defined %}
-    {% set have_edit_link = True %}
-    {% set githuburl = target.github_forkurl + "/edit/"
-      + target.github_branch + "/tool/" + currentpage.template %}
+  {% if target.github_forkurl is defined %}
+    {% set have_edit_link = False %}
+    {% if currentpage.md is defined %}
+        {% if currentpage.md.startswith("http://") or
+          currentpage.md.startswith("https://") %}
+          {# Leave have_edit_link = False #}
+        {% else %}
+          {% set have_edit_link = True %}
+          {% set githuburl = target.github_forkurl + "/edit/"
+            + target.github_branch
+            + "/content/" + currentpage.md %}
+        {% endif %}
+    {% elif currentpage.template is defined %}
+      {% set have_edit_link = True %}
+      {% set githuburl = target.github_forkurl + "/edit/"
+        + target.github_branch + "/tool/" + currentpage.template %}
+    {% endif %}
+    {% if target.is_pr_build is defined and target.is_pr_build and have_edit_link %}
+      {% set githuburl = githuburl + "?pr=/ripple/ripple-dev-portal/pull/"
+        + target.github_pr_id %}
+    {% endif %}
+    {% if not have_edit_link %}
+      {% set githuburl = target.github_forkurl %}
+    {% endif %}
+    <a href="{{githuburl}}" target="_blank" class="github-edit">Edit</a>
   {% endif %}
-  {% if target.is_pr_build is defined and target.is_pr_build and have_edit_link %}
-    {% set githuburl = githuburl + "?pr=/ripple/ripple-dev-portal/pull/"
-      + target.github_pr_id %}
-  {% endif %}
-  {% if not have_edit_link %}
-    {% set githuburl = target.github_forkurl %}
-  {% endif %}
-  <a href="{{githuburl}}" target="_blank" class="github-edit">Edit</a>
 </div><!-- /.github-edit -->