From c47f70590709795c057984d196ceffe809d727ae Mon Sep 17 00:00:00 2001 From: Matthieu Olivier Date: Tue, 1 Jan 2019 22:37:00 +0100 Subject: [PATCH 1/5] Activate generic importer + document usage --- docs/docs/quickstart.rst | 29 ++++++++++++++++++++++++++--- isso/__init__.py | 2 +- isso/migrate.py | 9 ++++++--- 3 files changed, 33 insertions(+), 7 deletions(-) diff --git a/docs/docs/quickstart.rst b/docs/docs/quickstart.rst index 8efd31d..1c60cf4 100644 --- a/docs/docs/quickstart.rst +++ b/docs/docs/quickstart.rst @@ -60,7 +60,8 @@ For more options, see :doc:`server ` and :doc:`client Migration --------- -You can import comments from Disqus_ or WordPress_. +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. 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 @@ -70,11 +71,33 @@ 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. -Now import the XML dump: +For any other comment system you can use the generic JSON format. It's up to you +to fit the format (see isso/tests/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 disqus-or-wordpress.xml + ~> isso -c /path/to/isso.cfg import -t [disqus|wordpress|generic] disqus-or-wordpress-or-generic.[xml|json] [100%] 53 threads, 192 comments .. _Disqus: https://disqus.com/ diff --git a/isso/__init__.py b/isso/__init__.py index a3da85b..6f783ce 100644 --- a/isso/__init__.py +++ b/isso/__init__.py @@ -225,7 +225,7 @@ def main(): imprt.add_argument("-n", "--dry-run", dest="dryrun", action="store_true", help="perform a trial run with no changes made") imprt.add_argument("-t", "--type", dest="type", default=None, - choices=["disqus", "wordpress"], help="export type") + choices=["disqus", "wordpress", "generic"], help="export type") imprt.add_argument("--empty-id", dest="empty_id", action="store_true", help="workaround for weird Disqus XML exports, #135") diff --git a/isso/migrate.py b/isso/migrate.py index 201dba5..98ebf4c 100644 --- a/isso/migrate.py +++ b/isso/migrate.py @@ -269,9 +269,10 @@ class Generic(object): - 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 name - - email: the author email - - website: the authot's website + - 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" """ @@ -351,6 +352,8 @@ def dispatch(type, db, dump, empty_id=False): cls = Disqus elif type == "wordpress": cls = WordPress + elif type == "generic": + cls = Generic else: with io.open(dump, encoding="utf-8") as fp: cls = autodetect(fp.read(io.DEFAULT_BUFFER_SIZE)) From 97ceaa1748f5efd24edef8669fe75764e05e2d78 Mon Sep 17 00:00:00 2001 From: Matthieu Olivier Date: Wed, 2 Jan 2019 13:14:28 +0100 Subject: [PATCH 2/5] Activate generic importer + document usage --- docs/docs/quickstart.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/docs/quickstart.rst b/docs/docs/quickstart.rst index 1c60cf4..42c54e2 100644 --- a/docs/docs/quickstart.rst +++ b/docs/docs/quickstart.rst @@ -72,7 +72,7 @@ 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 the format (see isso/tests/generic.json for an example): +to fit the format (see generic.json_ for an example): .. code-block:: A list of threads, each item being a dict with the following data: @@ -97,11 +97,12 @@ Now import the XML or JSON dump: .. code-block:: sh - ~> isso -c /path/to/isso.cfg import -t [disqus|wordpress|generic] disqus-or-wordpress-or-generic.[xml|json] + ~> isso -c /path/to/isso.cfg import -t [disqus|wordpress|generic] comment-dump.[xml|json] [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 ------------ From acb1e25193ed3ecac58475fa40a813f18c738e76 Mon Sep 17 00:00:00 2001 From: Matthieu Olivier Date: Wed, 2 Jan 2019 13:23:20 +0100 Subject: [PATCH 3/5] Code was not visible --- docs/docs/quickstart.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/docs/quickstart.rst b/docs/docs/quickstart.rst index 42c54e2..a5007d2 100644 --- a/docs/docs/quickstart.rst +++ b/docs/docs/quickstart.rst @@ -72,9 +72,10 @@ 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 the format (see generic.json_ for an example): +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 From e3d5741c5156b2f65046a7fb5f61e269d6dad222 Mon Sep 17 00:00:00 2001 From: root Date: Wed, 9 Jan 2019 13:41:38 +0100 Subject: [PATCH 4/5] 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 ------------ From b1ea9b2fb386b9ae7e506f622dbadd7780023ab1 Mon Sep 17 00:00:00 2001 From: Matthieu Olivier Date: Wed, 9 Jan 2019 13:54:21 +0100 Subject: [PATCH 5/5] Fix missing letter --- docs/docs/quickstart.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/quickstart.rst b/docs/docs/quickstart.rst index 36299af..d497274 100644 --- a/docs/docs/quickstart.rst +++ b/docs/docs/quickstart.rst @@ -62,7 +62,7 @@ Migration 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 `. +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