Consolidate current API tool documentation (#2169)

* Combine api tool documentation and create basic doc structure. * Update links to point to consolidated API document * Employ technical writing best practices * Add a link to API Blueprint * Fix link syntax * Fix build * Turn vale off for "Apiary" This may or may not work See errata-ai/vale#340 * Revert "Turn vale off for "Apiary"" This reverts commit 7afc314. * Add exception * Update link text --------- Co-authored-by: Sam Wright <[email protected]>
writethedocs · Jul 9, 2024 · a5c1c23 · a5c1c23
1 parent 53c1a42
commit a5c1c23
Show file tree

Hide file tree

Showing 9 changed files with 123 additions and 118 deletions.
diff --git a/docs/guide/api/api-documentation-tools.rst b/docs/guide/api/api-documentation-tools.rst
@@ -0,0 +1,114 @@
+=======================
+API documentation tools
+=======================
+
+Specialized descriptive languages help when writing API documentation.
+Some of our favorite descriptive languages include:
+
+* :ref:`blueprint`
+* Swagger
+
+When specifying a descriptive language for your API, you'll also need tools to create engaging
+documents. Several tools work best with our favorite descriptive languages:
+
+* :ref:`apiary-overview`
+* Aglio
+* :doc:`Sphinx </guide/tools/sphinx>`
+
+.. _apiary-overview:
+
+Apiary
+~~~~~~
+
+Apiary is a service that allows you to edit and host documentation online.
+
+Hosting Apiary docs
+-------------------
+
+Apiary provides a service for creating and hosting API documentation described in the :ref:`blueprint`
+or Swagger format. Once the API description is complete, Apiary generates interactive documentation in a
+three column layout. Example requests and responses are shown for every endpoint in multiple
+programming languages. It also enables the user to make requests to your live API.
+
+.. _apiary-building-docs:
+
+Building Apiary docs
+--------------------
+
+To build Apiary docs locally, follow these steps:
+
+1. `Install the Apiary CLI Tools. <https://help.apiary.io/tools/apiary-cli/>`_
+2. Navigate to the directory containing your ``.apib`` file.
+3. Run the following to validate your ``.apib`` file and create the HTML file::
+
+    apiary preview --path="myfile.apib" --output="myfile.html"
+
+4. View the document in your browser.
+
+.. _blueprint:
+
+API Blueprint
+~~~~~~~~~~~~~
+
+API Blueprint is a high-level language for describing web APIs. The goal of the API Blueprint format
+is to support the design-first philosophy for REST APIs; however, the format also works for
+documenting existing APIs. The files are saved with a `.apib` extension.
+
+The syntax combines Markdown syntax and Markdown Syntax for Object Notation (MSON). Markdown is a
+lightweight text formatting syntax and `MSON <https://github.com/apiaryio/mson>`_ is an extension
+of Markdown for describing data objects.
+
+Getting started with API Blueprint
+----------------------------------
+
+The quickest way to get started with API Blueprint is to use `Apiary <https://apiary.io/>`_ to edit and view your
+documentation by following these steps:
+
+1. Sign up for an account `on Apiary. <https://login.apiary.io/register>`_
+2. Follow the `API Blueprint Tutorial. <https://apiblueprint.org/documentation/tutorial.html>`_ to describe an API.
+
+Writing API Blueprint docs
+--------------------------
+
+The structure for an ``.apib`` file is::
+
+  Metadata
+  API Name
+  Resource Group
+    Resource
+      Action
+      Action
+    Resource
+  Resource Group
+  Data Structures
+
+``Metadata``:
+  describes the API Blueprint version
+
+``API Name``:
+  your API name
+
+``Resource Groups``:
+  describes a collection of related API endpoints
+
+``Resources``:
+  describes a specific API endpoint
+
+``Actions``:
+  describes specific HTTP verb actions to an endpoint
+
+``Data Structures``:
+  describes data used in your API requests/responses. By defining them in a separate section, they
+  can easily be reused.
+
+Building API Blueprint docs
+---------------------------
+
+The two most popular tools for generating documents from API Blueprints are :ref:`Apiary <apiary-building-docs>` and
+`Aglio <https://github.com/danielgtaylor/aglio>`_.
+
+Testing API docs
+~~~~~~~~~~~~~~~~
+
+When specifying an API in a descriptive language, you don't have to manually
+validate your documents. Tools like Dredd can test your documentation against the live API.
diff --git a/docs/guide/api/apiary.rst b/docs/guide/api/apiary.rst
diff --git a/docs/guide/api/apiblueprint.rst b/docs/guide/api/apiblueprint.rst
diff --git a/docs/guide/api/generating-documents.rst b/docs/guide/api/generating-documents.rst
diff --git a/docs/guide/api/languages.rst b/docs/guide/api/languages.rst
diff --git a/docs/guide/api/testing.rst b/docs/guide/api/testing.rst
diff --git a/docs/guide/index.rst b/docs/guide/index.rst
@@ -69,9 +69,7 @@ API documentation
 .. toctree::
    :maxdepth: 2
 
-   api/languages
-   api/generating-documents
-   api/testing
+   api/api-documentation-tools
 
 Contribution information
 ------------------------
@@ -89,4 +87,4 @@ Write the Docs resources
 * `WTD Slack Network <https://writethedocs.org/slack/>`__
 * `WTD Newsletters <https://writethedocs.org/newsletter/>`__
 * Twitter: http://twitter.com/writethedocs
-* Issues & feature requests: https://github.com/writethedocs/docs/issues
+* Issues & feature requests: https://github.com/writethedocs/docs/issues
diff --git a/docs/guide/tools/sphinx.rst b/docs/guide/tools/sphinx.rst
@@ -1,3 +1,5 @@
+.. _intro-sphinx:
+
 ======================
 Introduction to Sphinx
 ======================
@@ -27,8 +29,8 @@ complexity.
 Just know that some of the awkward syntax allows you to do more interesting
 things further down the line.
 In particular, it is extensible: it has a formal way of adding markup
-`directives`_ that allow more sophisticated parsing. 
-For example, Sphinx includes directives to relate documentation of 
+`directives`_ that allow more sophisticated parsing.
+For example, Sphinx includes directives to relate documentation of
 modules, classes and methods to the corresponding code.
 
 Installing Sphinx
@@ -105,12 +107,12 @@ following ``toctree`` directive in TopLevel1::
      Child1
      Child2
      Child3
- 
+
 Different Sphinx themes will have different ways of displaying the TOC
 in the sidebar. You can also configure whether or not to display the
 toctree directive as a mini-toc within the topic itself, by adding a
 ``:hidden:`` option to the ``toctree`` directive.
-     
+
 Writing docs
 ------------
 

diff --git a/vale/WTD/headings.yml b/vale/WTD/headings.yml
@@ -4,6 +4,7 @@ level: error
 scope: heading
 match: $sentence
 exceptions:
+  - Apiary
   - API
   - API Blueprint
   - ARID