Merge pull request #4 from apiaryio/smizell/mkdocs

Use mkdocs for documentation

CHANGELOG.md

@@ -1,5 +1,5 @@
 # Changelog
 All notable changes to the Refract project will be documented in this file.
 
-## [1.0.0]
+## [1.0.0-rc1]
 - Initial production-ready version of API Elements

README.md

@@ -1,20 +1,8 @@
 # API Elements
 API Elements is a structure for describing APIs and the complex data structures used within them. It also provides structures for defining parsing results for parsing API definitions from formats like API Blueprint and Swagger/OpenAPI Format.
 
-## Specification
-[API Elements Reference](./API Elements Reference.md)
+[Documentation and Reference][]
 
-The specification is built upon the [Refract][] format and is written using [MSON][].
+Please refer to the documentation and reference for more information.
 
-## Contributing
-Feel free report problems or propose new ideas using the API Blueprint GitHub
-[issues][].
-
-## License
-MIT License. See the [LICENSE](.LICENSE) file.
-
----
-
-[issues]: https://github.com/apiaryio/api-elements/issues
-[Refract]: https://github.com/refractproject/refract-spec
-[MSON]: https://github.com/apiaryio/mson
+[Documentation and Reference]: ./docs/index.md

docs/additional-information.md

@@ -0,0 +1,7 @@
+# Additional Information
+
+This page defines links and references for additional reading.
+
+- [Refract](https://github.com/refractproject/refract-spec) - Basis for API Elements' structure
+- [API Blueprint](https://apiblueprint.org/) - API description format that utilizes API Elements as its parsing results
+- [MSON](https://github.com/apiaryio/mson) - Data structure format that utilizes API Elements as its parsing results (see the Data Structure Elements)

API Elements Reference.md → docs/element-definitions.md

@@ -1,84 +1,13 @@
-# API Elements Reference
-
-**Version**: 1.0.0-rc1
-
-<!--
-  The TOC Atom lib doesn't like Markdown headings, so you have to remove items
-  that are pulled from API Blueprint examples on accident.
--->
-
-- [API Elements Reference](#api-elements-reference)
-  - [About this Document](#about-this-document)
-  - [Relationship of Elements](#relationship-of-elements)
-  - [I. Base API Element Definition](#i-base-api-element-definition)
-    - [Base API Element (object)](#base-api-element-object)
-  - [II. Core API Elements](#ii-core-api-elements)
-    - [Href (string)](#href-string)
-    - [Templated Href (string)](#templated-href-string)
-    - [Href Variables (Object Type)](#href-variables-object-type)
-    - [Data Structure (Base API Element)](#data-structure-base-api-element)
-    - [Asset (Base API Element)](#asset-base-api-element)
-    - [Resource (Base API Element)](#resource-base-api-element)
-    - [Transition (Base API Element)](#transition-base-api-element)
-    - [Category (Base API Element)](#category-base-api-element)
-    - [Copy (Base API Element)](#copy-base-api-element)
-    - [Protocol-specific Elements](#protocol-specific-elements)
-  - [III. Data Structure Elements](#iii-data-structure-elements)
-    - [Inheritance and Expanded Element](#inheritance-and-expanded-element)
-    - [Base Data Structure Element](#base-data-structure-element)
-    - [Data Structure Element (Base API Element)](#data-structure-element-base-api-element)
-    - [Type Reference (Ref Element)](#type-reference-ref-element)
-    - [Boolean Type (Boolean Element)](#boolean-type-boolean-element)
-    - [String Type (String Element)](#string-type-string-element)
-    - [Number Type (Number Element)](#number-type-number-element)
-    - [Array Type (Array Element)](#array-type-array-element)
-    - [Object Type (Object Element)](#object-type-object-element)
-    - [Enum Type (Data Structure Element)](#enum-type-data-structure-element)
-    - [Examples](#examples)
-  - [III. Parse Result Elements](#iii-parse-result-elements)
-    - [Parse Result (Base API Element)](#parse-result-base-api-element)
-    - [Annotation (Base API Element)](#annotation-base-api-element)
-    - [Source Map (Base API Element)](#source-map-base-api-element)
-    - [Link Relations](#link-relations)
-  - [IV. Refract Elements](#iv-refract-elements)
-
-## About this Document
-
-This document conforms to [RFC 2119][], which says:
-
-> The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119.
-
-[MSON][] is used throughout this document.
-
-## Relationship of Elements
-
-One purpose of the API Elements reference is to allow consumers to decouple their implementations from the structure of the document. Because of this, when consuming documents of API Elements, it is recommended to write code that queries the tree rather than looking for defined paths.
-
-It is also helpful to know the relationship between elements. The list below shows the relationship between the elements in this reference, but does not specify how the structure must be built.
-
-- Category (API)
-  - Copy
-  - Data Structure
-  - Category (Group of Resource Elements)
-  - Resource
-    - Copy
-    - Data Structure
-    - Category (Group of Transition Elements)
-    - Transition
-      - Copy
-      - Transaction
-        - Copy
-        - HTTP Request
-          - Asset
-        - HTTP Response
-          - Asset
-
-This main API Category element MAY also be wrapped in a Parse Result element for conveying parsing information, such as source maps, warnings, and errors.
-
-## I. Base API Element Definition
+# Element Definitions
+
+This defines all of the elements for use within API Elements documents.
+
+## Defining the Base API Element
 
 The API Elements reference relies on [Refract][] for its definition and structure. To make this reference document more understandable, this base element has been included and used throughout.
 
+This base element defines the structure of each element in this reference. Elements then extend upon this structure in their own definitions throughout.
+
 ### Base API Element (object)
 
 The Base API Element contains four properties: `element`, `meta`, `attributes`, and `content`, as defined below. This Element MAY be used recursively throughout the document, even as a value for each of its own meta or attributes.
@@ -140,7 +69,7 @@ An element MAY look like this, where `foo` is the element name, `id` is a meta a
 }
 ```
 
-## II. Core API Elements
+## Core API Elements
 
 ### Href (string)
 
@@ -600,7 +529,7 @@ HTTP response message.
 - `attributes`
     - `statusCode` (number) - HTTP response status code.
 
-## III. Data Structure Elements
+## Data Structure Elements
 
 ### Inheritance and Expanded Element
 
@@ -1283,7 +1212,7 @@ Note this needs an introduction of a new Data Structure element for any type - `
   }]
 ]]
 ```
-## III. Parse Result Elements
+## Parse Result Elements
 
 ### Parse Result (Base API Element)
 
@@ -1424,7 +1353,7 @@ the `inferred` link tells the user that the element was created based on some
 varying assumptions, and the URL to which the link points MAY provide an
 explanation on how and why it was inferred.
 
-## IV. Refract Elements
+## Refract Elements
 
 These elements and definitions are referenced as part of the base Refract specification for the purpose of identifying, referencing, and pointing to elements and their respective meta, attributes, or content.
 

docs/index.md

@@ -0,0 +1,33 @@
+# API Elements
+
+API Elements is a structure for describing APIs and the complex data structures used within them. It also provides structures for defining parsing results for parsing API definitions from formats like API Blueprint and Swagger/OpenAPI Format.
+
+## Reference
+
+- [Overview](./overview.md)
+- [Element Defintions](./element-definitions.md)
+- [Additional Information](./additional-information.md)
+
+The documentation is written using [MSON][].
+
+## Contributing
+
+Feel free report problems or propose new ideas using the API Elements GitHub
+[issues][].
+
+## About this Documentation
+
+This documentation conforms to [RFC 2119][], which says:
+
+> The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119.
+
+[MSON][] is used throughout this document to define elements and structures.
+
+## License
+MIT License. See the [LICENSE][] file.
+
+[RFC 2119]: https://datatracker.ietf.org/doc/rfc2119/
+[issues]: https://github.com/apiaryio/api-elements/issues
+[Refract]: https://github.com/refractproject/refract-spec
+[MSON]: https://github.com/apiaryio/mson
+[LICENSE]: https://github.com/apiaryio/api-elements/blob/master/LICENSE

docs/overview.md

@@ -0,0 +1,83 @@
+# API Elements Overview
+
+**Version**: 1.0.0-rc1
+
+## About API Elements
+
+API Elements exist to provide a standard and canonical way to interact with the elements of an API. These elements are usually found in description formats, such as API Blueprint and Swagger/OpenAPI Format, and are used in various contexts. The idea is that consumers of API Elements can use this single format while providing support for the other formats.
+
+An element is an individual piece that makes up an API. These can range from defining a resource or an HTTP request.
+
+The API Elements project defines elements used for:
+
+1. Describing an API
+1. Describing data structures used within that API
+1. Describing parse results when parsing API-related documents
+
+These elements also seek to provide a way to decouple APIs and their semantics from the implementation details.
+
+## Relationship of Elements
+
+One purpose of the API Elements reference is to allow consumers to decouple their implementations from the structure of the document. Because of this, when consuming documents of API Elements, it is recommended to write code that queries the tree rather than looking for defined paths.
+
+It is also helpful to know the relationship between elements. The list below shows the relationship between the elements in this reference, but does not specify how the structure must be built.
+
+- Category (API)
+    - Copy
+    - Data Structure
+    - Category (Group of Resource Elements)
+    - Resource
+        - Copy
+        - Data Structure
+        - Category (Group of Transition Elements)
+        - Transition
+            - Copy
+            - Transaction
+                - Copy
+                - HTTP Request
+                    - Copy
+                    - Data Structure
+                    - Asset
+                - HTTP Response
+                    - Copy
+                    - Data Structure
+                    - Asset
+
+This main API Category element MAY also be wrapped in a Parse Result element for conveying parsing information, such as source maps, warnings, and errors.
+
+## Basic Element
+
+Every element defined with API Elements has four primary pieces of data.
+
+- `element` (string) - defines the type of element used
+- `meta` (object) - an object that includes metadata about the element
+- `attributes` (object) - user-specified attributes for a given element
+- `content` - value of the element based on its type
+
+This structure is based on [Refract][], and is expanded and defined better in the [element definition](./element.definitions.md) file.
+
+Here is an example of what an element MAY look like.
+
+```json
+{
+  "element": "string",
+  "meta": {
+    "id": "foo",
+    "title": "Foo",
+    "description": "My foo element"
+  },
+  "content": "bar"
+}
+```
+
+Additional examples are provided throughout this documentation. As this shows, though, it allows for API Elements to only define data, but also metadata as well. This is especially important when providing source maps and adding human readable titles to values.
+
+## Consuming Documents
+
+As mentioned, for consumers, it is important to not couple code to the specific structure of an API Elements document. The common pattern is to reference elements by specifying a specific and strict path to those elements, but it is recommended to try to avoid this for sake of evolvability and safety.
+
+Given that API Elements use [Refract][], the structure of the document is recursive by nature. When looking for specific elements, it is best then to walk the tree to look for a match. Querying the tree means that your code will be decoupled from not only from specific API description documents, but it will also be decoupled from the structure of those documents.
+
+[Refract]: https://github.com/refractproject/refract-spec/blob/master/refract-spec.md
+[MSON]: https://github.com/apiaryio/mson
+[RFC 2119]: https://datatracker.ietf.org/doc/rfc2119/

docs/tools.md

@@ -0,0 +1,25 @@
+# Tools
+
+## [Fury](https://github.com/apiaryio/fury.js)
+
+Fury is a library for parsing API description documents and return API Elements.
+
+## [Drafter](https://github.com/apiaryio/drafter)
+
+Drafter is a library for parsing API Blueprint documents and return parse results in API Elements.
+
+## [Protagonist](https://github.com/apiaryio/protagonist)
+
+Protagonist is a Node.js wrapper for the Drafter library.
+
+## [Lodash API Description](https://github.com/apiaryio/lodash-api-description)
+
+A JavaScript library provides utility functions for consuming an API Elements document.
+
+## [Query Tool](https://github.com/apiaryio/refract-query)
+
+A tool for querying a Refract or API Elements document.
+
+## [Minim API Definition](https://github.com/refractproject/minim-api-description/)
+
+This JavaScript tool utilizes [Minim](https://github.com/refractproject/minim) for building and consuming API Elements.

mkdocs.yml

@@ -0,0 +1,8 @@
+site_name: API Elements
+pages:
+  - Home: 'index.md'
+  - Reference:
+    - Overview: 'overview.md'
+    - 'Element Definitions': 'element-definitions.md'
+    - 'Additional Information': 'additional-information.md'
+  - Tools: 'tools.md'