More docs cleanup

docs/contributing.md

@@ -9,7 +9,7 @@
 - Don't submit sloppy work.
 
 ```eval_rst
-.. Tip:: Before contributing: if you're making a code change, look through open pull requests to see if there's an open one for the feature/fix already.
+.. Tip:: Before contributing: if you're making a code change, look through open pull requests to see if there's one for the feature/fix already.
 ```
 
 ## Updating documentation
@@ -33,28 +33,42 @@ Installing dependencies comes in two forms.
 - To install the dependencies for Dingo, set the shell variable `COMPOSER=composer.dingo.json` before running `composer install` (ie `COMPOSER=composer.dingo.json composer install`). On Windows, you can use the NPM package [cross-env](https://npmjs.com/package/cross-env) to easily run a process with specific shell variables.
 
 ## Running tests
-> 💡TIP: It's a good idea to run all tests before you modify the code. That way, if the tests fail later, you can be sure it was (probably) due to something you added.
+```eval_rst
+.. Tip:: It's a good idea to run all tests before you modify the code. That way, if the tests fail later, you can be sure it was (probably) due to something you added.
+```
 
 - To run tests for Laravel, make sure the Laravel dependencies are installed by running `composer install`. Then run `composer test`. This will run all tests excluding the ones for Dingo and stop on the first failure.
  
 - To run tests for Dingo, make sure the Laravel dependencies are installed by running `COMPOSER=composer.dingo.json composer install`. Then run `COMPOSER=composer.dingo.json composer test`. This will run only the tests for Dingo and stop on the first failure.
 
-> 💡TIP: You can pass options to PHPUnit by putting them after a `--`. For instance, filter by using `composer test -- --filter can_fetch_from_responsefile_tag`.
+```eval_rst
+.. Tip:: You can pass options to PHPUnit by putting them after a :code:`--`. For instance, filter by using :code:`composer test -- --filter can_fetch_from_responsefile_tag`.
+```
 
-For faster test runs, you can run the tests in parallel with `composer test-parallel`.
+```eval_rst
+.. Tip:: For faster test runs, you can run the tests in parallel with :code:`composer test-parallel`. The :code:`--filter` option is not supported here, though.
+```
 
 ## Writing tests
-> 💡TIP: You should add tests to your changes, especially where the behaviour change is critical or important for reliability. If you don't know how, feel free to open a PR and ask for help.
+```eval_rst
+.. Tip:: You should add tests to your changes, especially where the behaviour change is critical or important for reliability. If you don't know how, feel free to open a PR and ask for help.
+```
 
 Tests are located in the tests/ folder. Currently, feature tests go in the `GenerateDocumentationTest` class in the base folder, unit tests go in their respective classes in the `Unit` folder, and tests for included strategies go in the `Strategies` folder. 
 
 Note that some of the unit and strategy tests extend PHPUnit\Framework\TestCase while others extend Orchestra\Testbench\TestCase. The first case is for tests that don't need any special Laravel functionality. The second case is for tests that depend on some Laravel functionality or helpers (like `storage_path` in `UseResponseFileTagTest` and `ResponseCallsTest` that depends on Laravel routing.)
 
-> 💡TIP: Avoid tests that make assertions on the generated HTML or Markdown output. It's a very unreliable testing approach. Instead assert on structured, consistent data like the parsed route output and Postman collection. 
+```eval_rst
+.. Note::  Avoid tests that make assertions on the generated HTML or Markdown output. It's a very unreliable testing approach. Instead assert on structured, consistent data like the parsed route output and Postman collection. 
+```
 
 ## Making pull requests
-- IMPORTANT: If your code changes how the generated documentation looks, please include "before" and "after" screenshots in your pull request. This will help the maintainers easily see the changes.
+```eval_rst
+.. Important:: If your code changes how the generated documentation looks, please include "before" and "after" screenshots in your pull request. This will help the maintainers easily see the changes.
+```
 
-> 💡TIP: If you need a project to test the generated doc output on, you can use [this](http://github.com/shalvah/thecensorshipapi). Replace the path in the `repositories` section of the `composer.json` to point to your local clone of scribe.
+```eval_rst
+.. Tip:: If you need a project to test the generated doc output on, you can use `this <http://github.com/shalvah/thecensorshipapi>`_. Replace the path in the :code:`repositories` section of the :code:`composer.json` to point to your local clone of Scribe.
+```
 
 - Add a short description to your PR (except it's so simple it fits in the title), so the reviewer knows what to look out for before looking through your changes. If you're fixing a bug, include a describe its behaviour and what your fix was. If you're adding a feature, explain what it is and why.

docs/customization.md

@@ -71,15 +71,17 @@ In the template, you have the `$baseUrl` and `$route` variables available to you
 .. Important:: Parameters which have been excluded from the example requests (see `Specifying Example Values <documenting-endpoint-query-parameters.html#specifying-example-values>`_) will not be present in :code:`cleanQueryParameters`, :code:`cleanBodyParameters`, or :code:`fileParameters`.
 ```
 
-You can also make use of some utilities in the class `\Knuckles\Scribe\Tools\WritingUtils` to help you easily output data in various forms (such as in key=value format or as a PHP array). Please take a look at that class and its usages in the included example request templates for details.
+```eval_rst
+.. Tip:: You can make use of some utilities in the class :code:`\Knuckles\Scribe\Tools\WritingUtils` to help you easily output data in various forms (such as in key=value format or as a PHP array). Please take a look at that class and its usages in the included example request templates for details.
+```
 
 Finally, add the language to the `example_languages` array in your config and generate your documentation as usual. 
 
 ## Customizing the code used in examples
-Customise existing language templates, follows the same process as described above: publish assets, then modify the Blade templates in `resources/views/vendor/scribe/partials/example-requests` as necessary.
+Customising existing language templates follows the same process as described above: publish assets, then modify the Blade templates in `resources/views/vendor/scribe/partials/example-requests` as necessary.
 
 ## Changing the Markdown templates
-If you'd like to do even more, you can take a look at editing the other Blade views.
+If you need to go even further, you can take a look at editing the included Blade views.
 
 ### Included views
 You should see the following Blade files when you publish views:
@@ -96,7 +98,9 @@ The following Blade files are present in the `partials` directory:
    - the `$postmanCollectionLink` string that contains the URL to the Postman file (typically `./collection.json`), and
    - the `$settings` array that contains `logo`, `languages` and `title`.
 
-> IMPORTANT: These Blade files are all configured for generating Markdown which is then turned into static HTML (by Pastel). Therefore, hardcoded and relative links are used (eg `<a href="./collection.json">`). For users using `laravel` type documentation, these links are then replaced in the generated HTML file with the correct helpers (eg `<a href="{{ url('docs.json') }}" >`).
+```eval_rst
+.. Important::  These Blade files are all configured for generating Markdown which is then turned into static HTML (by Pastel). Therefore, hardcoded and relative links are used (eg :code:`<a href="./collection.json">`). For users using :code:`laravel` type documentation, these links are afterwards replaced in the generated HTML file with the correct Blade helpers (eg :code:`<a href="{{ url('docs.json') }}" >`).
+```
 
 - `group.blade.php`: This is the template for a group of endpoints. For each group of endpoints, this file is rendered, and gets transformed into the corresponding group file (for instance, endpoints with group "User Management" are passed through this template to create the file `groups/user-management.md`). It has access to the following variables:
    - `$groupName`,