docs: make a real documentation

swagindustries · Aug 19, 2020 · 1c5b4fc · 1c5b4fc
1 parent 4dba6fe
commit 1c5b4fc
Show file tree

Hide file tree

Showing 9 changed files with 283 additions and 225 deletions.
diff --git a/.gitignore b/.gitignore
@@ -1,4 +1,5 @@
 composer.lock
 vendor
 .php_cs.cache
-tests/TestApplication/var
+tests/TestApplication/var
+.couscous
diff --git a/README.md b/README.md
@@ -5,12 +5,18 @@ Melodiia
 
 Finally some competitor to ApiPlatform.
 
+Melodiia has been designed to do exactly what you want it does. No magic here. It's just a set of tools that
+work nicely with Symfony.
+
 Features
 --------
 
 - Adds a documentation endpoint with help of swagger
 - Set of api responses
-- Uses Symfony Form as input, because Symfony Serializer is not ready for that
+- Uses Symfony Form as input
+- CRUD controllers
+- Error management
+- Output format as [json-api](https://jsonapi.org/), a format that has 1.x version
 
 Install
 -------
@@ -19,32 +25,18 @@ Install
 composer require swag-industries/melodiia
 ```
 
-### Symfony setup
-
-Add the bundle to your bundle list:
-
-```php
-SwagIndustries\Melodiia\Bridge\Symfony\MelodiiaBundle::class => ['all' => true]
-```
-
-Setup the configuration:
-
-```yaml
-# config/packages/melodiia.yaml
-
-melodiia:
-    apis:
-        main:
-            base_path: /
-```
+The recipe will automatically create the configuration file `melodiia.yaml`. If you decided to not execute this recipe,
+please refer to the
+[recipe repository of Symfony](https://github.com/symfony/recipes-contrib/tree/master/swagindustries/melodiia).
 
-### Documentation 
+### Learn more 
 
- - [Configure my first crud operations !](./docs/Crud.md)
- - [Integration with Symfony ](./docs/Symfony.md)
- - [Presentation of Melodiia @Biig-io](https://docs.google.com/presentation/d/1dtxUOzZFGRq7Ar5YV5aZ6AN60RhDbf_0OcXKj5iiDS8/edit?usp=sharing)
+- [Getting Started](./docs/getting-started.md)
+- [Configure my first crud operations !](./docs/Crud.md)
+- [Integration with Symfony ](./docs/Symfony.md)
+- [Presentation of Melodiia @Biig-io](https://docs.google.com/presentation/d/1dtxUOzZFGRq7Ar5YV5aZ6AN60RhDbf_0OcXKj5iiDS8/edit?usp=sharing)
 
-Feel free to open an issue, if you encounter problems implementing Melodiia.
+Feel free to open an issue, if you encounter problems while implementing Melodiia.
 
 FAQ
 ---

diff --git a/couscous.yml b/couscous.yml
@@ -0,0 +1,34 @@
+template:
+    url: https://github.com/Nek-/Template-Light
+
+github:
+    user: SwagIndustries
+    repo: Melodiia
+
+exclude:
+    - vendor
+    - %gitignore%
+cname: melodiia.swag.industries
+
+branch: gh-pages
+
+
+title: Melodiia Documentation
+subTitle: Take control of your API
+menu:
+    items:
+        home:
+            text: Home page
+            relativeUrl: index.html
+        getting_started:
+            text: Getting Started
+            relativeUrl: docs/getting-started.html
+        filters:
+            text: Using filters
+            relativeUrl: docs/filters.html
+        config:
+            text: Configuration Reference
+            relativeUrl: docs/config-reference.html
+        cruds:
+            text: CRUD Reference
+            relativeUrl: docs/crud-controllers.html
diff --git a/docs/Crud.md b/docs/Crud.md
diff --git a/docs/Symfony.md b/docs/Symfony.md
diff --git a/docs/config-reference.md b/docs/config-reference.md
@@ -0,0 +1,17 @@
+Configuration Reference of Melodiia
+===================================
+
+```yaml
+melodiia:
+    apis:
+        # Define as much APIs you want here.
+        main:
+            base_path: /api/v1
+            pagination:
+                # Using this query attribute you can change the max per page
+                max_per_page_attribute: max_per_page
+    # Melodiia comes with some form types to help you build your application. You can enable them here.
+    # This is the default configuration
+    form_extensions:
+        datetime: true
+```
diff --git a/docs/crud-controllers.md b/docs/crud-controllers.md
@@ -0,0 +1,38 @@
+About CRUD Controllers
+======================
+
+Here are all the controllers for your CRUD.
+
+| CRUD action       | Service name                     |
+|-------------------|----------------------------------|
+| Create            | melodiia.crud.controller.create  |
+| Read (collection) | melodiia.crud.controller.get_all |
+| Read (item)       | melodiia.crud.controller.get     |
+| Update            | melodiia.crud.controller.update  |
+| Delete            | melodiia.crud.controller.delete  |
+
+CRUD Controllers have options, here are a list of them and their availability by controller:
+
+| Option name                             | Create | Read | Update | Delete |
+|-----------------------------------------|--------|------|--------|--------|
+| melodiia_model                          | x      | x    | x      | x      |
+| melodiia_form                           | x      |      | x      |        |
+| melodiia_clear_missing                  | x      |      | x      |        |
+| melodiia_serialization_group            |        | x    |        |        |
+| melodiia_security_check                 | x      | x    | x      | x      |
+| melodiia_max_per_page                   |        | x    |        |        |
+| melodiia_max_per_page_allowed           |        | x    |        |        |
+| melodiia_allow_user_define_max_per_page |        | x    |        |        |
+
+Example of route using options:
+
+```yaml
+acme_article_get_collection:
+    path: /api/v1/articles
+    controller: 'melodiia.crud.controller.get_all'
+    methods: 'GET'
+    defaults:
+        melodiia_model: App\Entity\Article
+        melodiia_serialization_group: "list-article"
+        melodiia_max_per_page: 25
+```