Rollback quickstart + split documentation for advanced migrations

docs/docs/extras/advanced-migration.rst

@@ -0,0 +1,71 @@
+Advanced Migration
+==================
+
+In quickstart we saw you can import comments from Disqs or WordPress. But there
+are a many other comments system and you could be using one of them.
+
+Isso provides a way to import such comments, however it's up to you to :
+
+- dump comments
+- fit the data to the following JSON format
+
+.. code-block::
+
+    A list of threads, each item being a dict with the following data:
+
+    - id: a text representing the unique thread id (note: by default isso
+          associates this ID to the article URL, but it can be changed on
+          client side with "data-isso-id" - see :doc:`client configuration <../configuration/client>` )
+    - title: the title of the thread
+    - comments: the list of comments
+
+        Each item in that list of comments is a dict with the following data:
+
+        - id: an integer with the unique id of the comment inside the thread
+          (it can be repeated among different threads); this will be used to
+          order the comment inside the thread
+        - author: the author's name
+        - email: the author's email
+        - website: the author's website
+        - remote_addr: the author's IP
+        - created: a timestamp, in the format "%Y-%m-%d %H:%M:%S"
+
+Example:
+
+.. code-block:: json
+    [
+        {
+            "id": "/blog/article1",
+            "title": "First article!"
+            comments": [
+                {
+                    "author": "James",
+                    "created": "2018-11-28 17:24:23",
+                    "email": "email@mail.com",
+                    "id": "1",
+                    "remote_addr": "127.0.0.1",
+                    "text": "Great article!",
+                    "website": "http://fefzfzef.frzr"
+                },
+                {
+                    "author": "Harold",
+                    "created": "2018-11-28 17:58:03",
+                    "email": "email2@mail.com",
+                    "id": "2",
+                    "remote_addr": "",
+                    "text": "I hated it...",
+                    "website": ""
+                }
+            ]
+        }
+    ]
+
+Keep in mind that isso expects to have an array, so keep the opening and ending square bracket even if you have only one article thread!
+
+Next you can import you json dump:
+
+.. code-block:: sh
+
+    ~> isso -c /path/to/isso.cfg import -t generic comment-dump.json
+    [100%]  53 threads, 192 comments
+

docs/docs/quickstart.rst

@@ -60,8 +60,9 @@ For more options, see :doc:`server <configuration/server>` and :doc:`client
 Migration
 ---------
 
-You can import comments from Disqus_ or WordPress_. You can also import comments
+Isso provides a tool for importing comments from Disqus_ or WordPress_.
-issued from any comment system but you have to stick a specific json format.
+You can also import comments form any other comment system, but this topic is more
+complex and covered in :doc:`advanced migration <extra/advanced-migration>`.
 
 To export your comments from Disqus, log into Disqus, go to your website, click
 on *Discussions* and select the *Export* tab. You'll receive an email with your
@@ -71,39 +72,15 @@ To export comments from your previous WordPress installation, go to *Tools*,
 export your data. It has been reported that WordPress may generate broken XML.
 Try to repair the file using ``xmllint`` before you continue with the import.
 
-For any other comment system you can use the generic JSON format. It's up to you
+Now import the XML dump:
-to fit to the format (see generic.json_ for an example):
-
-.. code-block::
-
-    A list of threads, each item being a dict with the following data:
-
-        - id: a text representing the unique thread id
-        - title: the title of the thread
-        - comments: the list of comments
-
-    Each item in that list of comments is a dict with the following data:
-
-        - id: an integer with the unique id of the comment inside the thread
-          (it can be repeated among different threads); this will be used to
-          order the comment inside the thread
-        - author: the author's name
-        - email: the author's email
-        - website: the author's website
-        - remote_addr: the author's IP
-        - created: a timestamp, in the format "%Y-%m-%d %H:%M:%S"
-
-
-Now import the XML or JSON dump:
 
 .. code-block:: sh
 
-    ~> isso -c /path/to/isso.cfg import -t [disqus|wordpress|generic] comment-dump.[xml|json]
+    ~> isso -c /path/to/isso.cfg import -t [disqus|wordpress] disqus-or-wordpress.xml
     [100%]  53 threads, 192 comments
 
 .. _Disqus: https://disqus.com/
 .. _WordPress: https://wordpress.org/
-.. _generic.json: https://github.com/posativ/isso/blob/master/isso/tests/generic.json
 
 Running Isso
 ------------