importer - add documentation

docs/importer.rst

@@ -0,0 +1,56 @@
+=================================
+ Import from other blog software
+=================================
+
+Description
+===========
+
+``importer.py`` is a command line tool for converting articles from other
+software to ReStructuredText. The supported formats are:
+
+- Wordpress XML export
+- Dotclear export
+- RSS/ATOM feed
+
+The conversion from HTML to ReStructuredText relies on `pandoc
+<http://johnmacfarlane.net/pandoc/>`_. For Dotclear, if the source posts are
+written with Markdown syntax, they will not be converted (as Pelican also
+supports Markdown).
+
+Usage
+"""""
+
+| importer.py [-h] [--wpfile] [--dotclear] [--feed] [-o OUTPUT]
+|                    [--dir-cat]
+|                    input
+
+Optional arguments:
+"""""""""""""""""""
+
+  -h, --help            show this help message and exit
+  --wpfile              Wordpress XML export
+  --dotclear            Dotclear export
+  --feed                Feed to parse
+  -o OUTPUT, --output OUTPUT
+                        Output path
+  --dir-cat             Put files in directories with categories name
+
+Examples
+========
+
+for Wordpress::
+
+    $ python2 tools/importer.py --wpfile -o ~/output ~/posts.xml
+
+for Dotclear::
+
+    $ python2 tools/importer.py --dotclear -o ~/output ~/backup.txt
+
+
+Tests
+=====
+
+To test the module, one can use sample files:
+
+- for Wordpress: http://wpcandy.com/made/the-sample-post-collection
+- for Dotclear: http://themes.dotaddict.org/files/public/downloads/lorem-backup.txt

docs/index.rst

@@ -61,5 +61,6 @@ A french version of the documentation is available at :doc:`fr/index`.
    themes
    internals
    pelican-themes
+   importer
    faq
    contribute

tools/importer.py

@@ -214,8 +214,8 @@ def main(input_type, input, output_path, dircat=False):
 
 if __name__ == '__main__':
     parser = argparse.ArgumentParser(
-            description="Transform even feed or XML files to rst files."
+            description="Transform feed, Wordpress or Dotclear files to rst files."
-                    "Be sure to have pandoc installed")
+                        "Be sure to have pandoc installed")
 
     parser.add_argument(dest='input', help='The input file to read')
     parser.add_argument('--wpfile', action='store_true', dest='wpfile',
@@ -223,7 +223,7 @@ if __name__ == '__main__':
     parser.add_argument('--dotclear', action='store_true', dest='dotclear',
             help='Dotclear export')
     parser.add_argument('--feed', action='store_true', dest='feed',
-            help='feed to parse')
+            help='Feed to parse')
     parser.add_argument('-o', '--output', dest='output', default='output',
             help='Output path')
     parser.add_argument('--dir-cat', action='store_true', dest='dircat',
@@ -238,6 +238,6 @@ if __name__ == '__main__':
     elif args.feed:
         input_type = 'feed'
     else:
-        print "you must provide either --wpfile or --feed options"
+        print "you must provide either --wpfile, --dotclear or --feed options"
         exit()
     main(input_type, args.input, args.output, dircat=args.dircat)