Merge pull request #7 from apiaryio/smizell/updates-after-rtd

Small fixes after building on RTD
apiaryio · Mar 2, 2016 · 6c5e4a7 · 6c5e4a7
2 parents 87b6e0d + c110477
commit 6c5e4a7
Show file tree

Hide file tree

Showing 5 changed files with 10 additions and 16 deletions.
diff --git a/README.md b/README.md
@@ -1,8 +1,6 @@
 # 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.
 
-[Documentation and Reference][]
+## Documentation and Reference
 
-Please refer to the documentation and reference for more information.
-
-[Documentation and Reference]: ./docs/index.md
+Please refer to the [documentation and reference](http://api-elements.readthedocs.org/en/latest/) for more information.
diff --git a/docs/element-definitions.md b/docs/element-definitions.md
@@ -1,6 +1,6 @@
 # Element Definitions
 
-This defines all of the elements for use within API Elements documents.
+This document defines all of the elements for use within API Elements.
 
 ## Defining the Base API Element
 

diff --git a/docs/index.md b/docs/index.md
@@ -2,14 +2,6 @@
 
 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
@@ -24,6 +16,7 @@ This documentation conforms to [RFC 2119][], which says:
 [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/

diff --git a/docs/overview.md b/docs/overview.md
@@ -2,6 +2,8 @@
 
 **Version**: 1.0.0-rc1
 
+**Mime Type**: TBD
+
 ## 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.
@@ -70,13 +72,13 @@ Here is an example of what an element MAY look like.
 }
 ```
 
-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.
+Additional examples are provided throughout this documentation for specific API Elements. As this shows, though, it allows for API Elements to not 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.
+As mentioned, for consumers, it is important to not couple code to the specific structure of an API Elements document. The common pitfall 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.
+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 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

diff --git a/mkdocs.yml b/mkdocs.yml
@@ -6,3 +6,4 @@ pages:
     - 'Element Definitions': 'element-definitions.md'
     - 'Additional Information': 'additional-information.md'
   - Tools: 'tools.md'
+repo_url: 'https://github.com/apiaryio/api-elements'