From 2cab223a8c33fce7cf306581663e210eeace3565 Mon Sep 17 00:00:00 2001
From: Alice <alice.poggioli@hotmail.fr>
Date: Thu, 7 May 2020 15:46:12 +0200
Subject: [PATCH] Add how to use sibserver

---
 .../how-to-use-sib-server.rst                 | 126 ++++++++++--------
 1 file changed, 71 insertions(+), 55 deletions(-)

diff --git a/source/import_documentation/how-to-use-sib-server.rst b/source/import_documentation/how-to-use-sib-server.rst
index 12d1fa0..3d46c19 100644
--- a/source/import_documentation/how-to-use-sib-server.rst
+++ b/source/import_documentation/how-to-use-sib-server.rst
@@ -4,7 +4,7 @@ How to use SiB server
 Once we've `install you server <install-sib-server.html>`__, we now are going to see how to use you it.
 
 Django references
------------------
+^^^^^^^^^^^^^^^
 As SiB server is a DjangoLDP server, you'll need some parts of Django documentation : 
 
     * `The Django models documentation <https://docs.djangoproject.com/fr/2.2/topics/db/models/>`__
@@ -42,14 +42,10 @@ the Linked Data Protocol standard. For local users it can be generated
 at runtime, but for some resources which are from distant servers this
 is required to be stored
 
-Creating your first model
+1. Creating your first model
 ==========================
 
-1. Create your django model inside a file
-   sibserver/sibserver/models.py 
-   
- .. note:: 
-   The container_path will be use to resolve instance iri and container iri In the future it could also be used to auto configure django router (e.g. urls.py)
+Create your django model inside a file sibserver/sibserver/models.py 
 
 .. code:: python
 
@@ -59,10 +55,17 @@ Creating your first model
        name = models.CharField(max_length=255)
        deadline = models.DateTimeField()
 
-1.1. Configure container path (optional) 
 
-.. note:: 
-   By default it will be “todos/” with an S for model called Todo
+2. Add Meta class to your model
+================================
+
+Container path
+--------------
+Here you gonna configure the url within you'll get your container. 
+By default it will be “todos/” with an S for model called Todo.
+
+ .. warning:: 
+   We should define what is a container in more detail.
 
 .. code:: python
 
@@ -73,8 +76,13 @@ Creating your first model
       class Meta:
             container_path = "/my-path/"
 
+ .. note:: 
+   The container_path will be use to resolve instance iri and container iri In the future it could also be used to auto configure django router (e.g. urls.py)
 
-1.2. Configure field visibility (optional) : put in `serializer_fields` the list of field name you want to show.
+
+Serialized fields
+-----------------
+You can configure field visibility (optional) : put in `serializer_fields` the list of field name you want to show.
 
 .. code:: python
 
@@ -91,11 +99,10 @@ Creating your first model
 
 Only ``name`` will be serialized
    
- .. note:: 
-   At this stage you can limit access to certain fields of models using
-   For example, if you have a model with a related field with type
-   **django.contrib.auth.models.User** you don’t want to show personal
-   details or password hashes.
+At this stage you can limit access to certain fields of models using
+For example, if you have a model with a related field with type
+**django.contrib.auth.models.User** you don’t want to show personal
+details or password hashes.
 
 E.g.
 
@@ -110,7 +117,42 @@ E.g.
     parameter as an argument to LDPViewSet.urls(), and filtered if you set
     the excludes= parameter.
 
-2. Add a url in your urls.py:
+auto_author
+------------
+
+This property allows to associate a model with the logged in user.
+
+.. code:: python
+
+   class MyModel(models.Model):
+       author_user = models.ForeignKey(settings.AUTH_USER_MODEL)
+       
+       class Meta:
+           auto_author = 'author_user'
+
+Now when an instance of ``MyModel`` is saved, its ``author_user``
+property will be set to the current user.
+
+nested_fields
+--------------
+
+list of ForeignKey, ManyToManyField, OneToOneField and their reverse
+relations. When a field is listed in this parameter, a container will be
+created inside each single element of the container.
+
+In the following example, besides the urls ``/members/`` and
+``/members/<pk>/``, two other will be added to serve a container of the
+skills of the member: ``/members/<pk>/skills/`` and
+``/members/<pk>/skills/<pk>/``
+
+.. code:: python
+
+   <Model>._meta.nested_fields=["skills"]
+
+
+3. Create a road for each model
+===============================
+Add a url in your urls.py:
 
 .. code:: python
 
@@ -133,8 +175,9 @@ You could also only use this line in settings.py instead:
 
    ROOT_URLCONF = 'djangoldp.urls'
 
-3. In the settings.py file, add your application name at the beginning
-   of the application list, and add the following lines
+3. Set up your application
+============================
+In the settings.py file, add your application name at the beginning of the application list, and add the following lines
 
 .. code:: python
 
@@ -160,7 +203,9 @@ You could also only use this line in settings.py instead:
  .. note:: 
    More documentation about context is coming soon
 
-4. You can also register your model for the django administration site in admin.py.
+4. Register your model in the Django administration
+======================================================
+You can also register your model for the django administration site in admin.py.
 
 .. code:: python
 
@@ -169,47 +214,18 @@ You could also only use this line in settings.py instead:
 
    admin.site.register(Todo)
 
-5. You then need to have your WSGI server pointing on
+You then need to have your WSGI server pointing on
    sibserver/sibserver/wsgi.py
 
-6. You will probably need to create a super user
+5. Create a super user
+========================
+You will probably need to create a super user
 
 .. code:: bash
 
    $ ./manage.py createsuperuser
 
 
-auto_author
-~~~~~~~~~~~
-
-This property allows to associate a model with the logged in user.
-
-.. code:: python
-
-   class MyModel(models.Model):
-       author_user = models.ForeignKey(settings.AUTH_USER_MODEL)
-       
-       class Meta:
-           auto_author = 'author_user'
-
-Now when an instance of ``MyModel`` is saved, its ``author_user``
-property will be set to the current user.
-
-nested_fields
-^^^^^^^^^^^^^
-
-list of ForeignKey, ManyToManyField, OneToOneField and their reverse
-relations. When a field is listed in this parameter, a container will be
-created inside each single element of the container.
-
-In the following example, besides the urls ``/members/`` and
-``/members/<pk>/``, two other will be added to serve a container of the
-skills of the member: ``/members/<pk>/skills/`` and
-``/members/<pk>/skills/<pk>/``
-
-.. code:: python
-
-   <Model>._meta.nested_fields=["skills"]
 
 Permissions
 ===========
@@ -333,7 +349,7 @@ custom ``view_set``:
 
 
 view_set
-~~~~~~~~
+-----------
 
 In case of custom viewset, you can use
 
@@ -357,7 +373,7 @@ possible de create a file named ``djangoldp_urls.py``. It will be
 executed like an ``urls.py`` file
 
 Pagination
-----------
+-----------
 
 To enable pagination feature just add this configuration to the server
 ``settings.py`` :
-- 
GitLab