From e3d5741c5156b2f65046a7fb5f61e269d6dad222 Mon Sep 17 00:00:00 2001 From: root Date: Wed, 9 Jan 2019 13:41:38 +0100 Subject: [PATCH] Rollback quickstart + split documentation for advanced migrations --- docs/docs/extras/advanced-migration.rst | 71 +++++++++++++++++++++++++ docs/docs/quickstart.rst | 33 ++---------- 2 files changed, 76 insertions(+), 28 deletions(-) create mode 100644 docs/docs/extras/advanced-migration.rst diff --git a/docs/docs/extras/advanced-migration.rst b/docs/docs/extras/advanced-migration.rst new file mode 100644 index 0000000..1675bfd --- /dev/null +++ b/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 + diff --git a/docs/docs/quickstart.rst b/docs/docs/quickstart.rst index a5007d2..36299af 100644 --- a/docs/docs/quickstart.rst +++ b/docs/docs/quickstart.rst @@ -60,8 +60,9 @@ For more options, see :doc:`server ` and :doc:`client Migration --------- -You can import comments from Disqus_ or WordPress_. You can also import comments -issued from any comment system but you have to stick a specific json format. +Isso provides a tool for importing comments from Disqus_ or WordPress_. +You can also import comments form any other comment system, but this topic is more +complex and covered in :doc:`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 -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: +Now import the XML 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 ------------