Update docs

docs/architecture.md

@@ -1,12 +1,16 @@
-# Architecture
-Read this page if you want a deeper understanding of how this works (for instance, for the purpose of contributing).
+# How Scribe works
+Read this page if you want a deeper understanding of how Scribe works (for instance, for the purpose of contributing).
 
-- When the `generate` command is run, it fetches all your application's routes from Laravel's (or DIngo's) Route facade.
+- When the `generate` command is run, the Generator fetches all your application's routes from Laravel's (or DIngo's) Route facade.
 - Next, the RouteMatcher uses the rules in your config to determine what routes to generate documentation for, as well as extract any specific configuration for them. This configuration is passed to the next stages.
-- The Generator processes each route. This entails:
-  - Fetching the route action (controller, method) via Reflection (along with their corresponding docblocks). These are used in the remaining stages below.
-  - Determining and obtaining info on body parameters, query parameters and headers to be added to the route's documentation.
-  - Obtaining a sample response.
-- The generate command uses information from these parsed routes and other configuration to generate a Markdown file via Blade templating.
-- This Markdown file is passed to Pastel, which transforms it into HTML, CSS and JavaScript assets.
-- If enabled, a Postman collection is generated as well.
+- The Generator processes each route. This means fetching the route action (controller, method) and using the configured strategies to extract the following:
+  - route metadata (name, description, group name, group description, auth status)
+  - url parameters
+  - body parameters
+  - query parameters
+  - headers
+  - fields in the response
+  - sample responses
+- Next, the Writer uses information from these parsed routes and other configuration to generate a Markdown file via Blade templating.
+- This Markdown file is passed to [Pastel](https://github.com/knuckleswtf/pastel), which wraps them in a theme and converts them into HTML, CSS and JS.
+- If enabled, a Postman collection is generated as wel, via the PostmanCollectionWriter.

docs/contributing.md

@@ -27,6 +27,10 @@ To link to a page inside another, you can use Markdown links, but then replace t
 .. Note:: The rest of this document is only important if you're making code changes.
 ```
 
+```eval_rst
+.. Tip:: You can check out `How Scribe works <architecture.html>`_ to gain a deeper understanding that can help you when contributing. 
+```
+
 ## Installing dependencies
 Installing dependencies comes in two forms.
 - To install the regular Laravel dependencies, run `composer install`.  

docs/description.md

@@ -1,16 +0,0 @@
-# How Scribe works
-Read this page if you want a deeper understanding of how Scribe works (for instance, for the purpose of contributing).
-
-- When the `generate` command is run, the Generator fetches all your application's routes from Laravel's (or DIngo's) Route facade.
-- Next, the RouteMatcher uses the rules in your config to determine what routes to generate documentation for, as well as extract any specific configuration for them. This configuration is passed to the next stages.
-- The Generator processes each route. This means fetching the route action (controller, method) and using the configured strategies to extract the following:
-  - route metadata (name, description, group name, group description, auth status)
-  - url parameters
-  - body parameters
-  - query parameters
-  - headers
-  - fields in the response
-  - sample responses
-- Next, the Writer uses information from these parsed routes and other configuration to generate a Markdown file via Blade templating.
-- This Markdown file is passed to [Pastel](https://github.com/knuckleswtf/pastel), which wraps them in a theme and converts them into HTML, CSS and JS.
-- If enabled, a Postman collection is generated as wel, via the PostmanCollectionWriter.

docs/index.md

@@ -24,7 +24,7 @@ Generate API documentation for humans from your Laravel/Lumen/[Dingo](https://gi
 * [Configuration](config.md)
 * [Troubleshooting and Debugging](troubleshooting.md)
 * [Advanced customization](customization.md)
-* [How this works](description.md)
+* [How Scribe works](architecture.md)
 * [Extending functionality with plugins](plugins.md)
 * [Contributing to Scribe](contributing.md)