diff --git a/docs/guide/api/api-documentation-tools.rst b/docs/guide/api/api-documentation-tools.rst new file mode 100644 index 0000000000..a45393154c --- /dev/null +++ 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 ` + +.. _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. `_ +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 `_ 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 `_ to edit and view your +documentation by following these steps: + +1. Sign up for an account `on Apiary. `_ +2. Follow the `API Blueprint Tutorial. `_ 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 ` and +`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 deleted file mode 100644 index 1d27de09bb..0000000000 --- a/docs/guide/api/apiary.rst +++ /dev/null @@ -1,21 +0,0 @@ -====== -Apiary -====== - -Hosting docs ------------- - -Apiary provides a service for creating and hosting API documentation described in the API 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 docs -------------- - -To build Apiary style docs locally, you need to install the Apiary CLI Tools. The full instructions are available `here. `_ - -Once it is installed, navigate to the directory containing your ``.apib`` file and run:: - - apiary preview --path="myfile.apib" --output="myfile.html" - -This will validate your ``.apib`` file and create the HTML file. You can then view the document in your browser. diff --git a/docs/guide/api/apiblueprint.rst b/docs/guide/api/apiblueprint.rst deleted file mode 100644 index e33c3c1f60..0000000000 --- a/docs/guide/api/apiblueprint.rst +++ /dev/null @@ -1,53 +0,0 @@ -============= -API Blueprint -============= - -API Blueprint is a high-level language for describing web APIs. The syntax is a combination of Markdown syntax and Markdown Syntax for Object Notation (MSON), and the files are saved with a `.apib` extension. Markdown is a lightweight text formatting syntax. `MSON `_ is an extension of Markdown for describing data objects. - -The goal of the API Blueprint format is to support the design-first philosophy for REST APIs; however, the format works just as well for documenting existing APIs. - -Getting started ---------------- - -The quickest way to get started is to use `Apiary `_ to edit and view your documentation. Apiary is a service that allows you to edit and host documentation online. Start by signing up for an account `on Apiary. `_ -Next, continue with the `API Blueprint Tutorial. `_ It provides a good overview of how to describe a basic API. - -Writing 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``: - is 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 docs -------------- - -The two most popular tools for generating documents from API Blueprints are Apiary and `Aglio `_. - -* :ref:`apiary-building-docs` with Apiary. diff --git a/docs/guide/api/generating-documents.rst b/docs/guide/api/generating-documents.rst deleted file mode 100644 index c12356f980..0000000000 --- a/docs/guide/api/generating-documents.rst +++ /dev/null @@ -1,13 +0,0 @@ -==================== -Generating documents -==================== - -If you're specifying your API in a descriptive language, you're going to need tools to create engaging documents. Below we talk about some of the tools that work best with the languages we like to use. - -.. toctree:: - :maxdepth: 2 - - apiary - -* Aglio -* Sphinx diff --git a/docs/guide/api/languages.rst b/docs/guide/api/languages.rst deleted file mode 100644 index c871348d86..0000000000 --- a/docs/guide/api/languages.rst +++ /dev/null @@ -1,12 +0,0 @@ -========= -Languages -========= - -Writing API documentation works best when using specialized descriptive languages. Below we talk about some of our favorites and the ones we find do the job the best. - -.. toctree:: - :maxdepth: 2 - - apiblueprint - -* Swagger diff --git a/docs/guide/api/testing.rst b/docs/guide/api/testing.rst deleted file mode 100644 index 79647b8d2c..0000000000 --- a/docs/guide/api/testing.rst +++ /dev/null @@ -1,11 +0,0 @@ -======= -Testing -======= - -If you're specifying your API in a descriptive language, you don't have to rely on manually validating your documents anymore. Below we talk about tools you can use to test your documentation against the live API. - -.. toctree:: - :maxdepth: 2 - - -* Dredd diff --git a/docs/guide/index.rst b/docs/guide/index.rst index fb227b4ff0..5a603111e4 100644 --- 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 `__ * `WTD Newsletters `__ * Twitter: http://twitter.com/writethedocs -* Issues & feature requests: https://github.com/writethedocs/docs/issues \ No newline at end of file +* Issues & feature requests: https://github.com/writethedocs/docs/issues diff --git a/docs/guide/tools/sphinx.rst b/docs/guide/tools/sphinx.rst index 978233e653..a624a0db5e 100644 --- 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 index 076d21056a..1e40483e4c 100644 --- 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