Improve documentation

README.rst

@@ -19,13 +19,13 @@ discodoc
 *****
 About
 *****
-`discodoc` - create documents from Discourse content easily.
+`discodoc` - create `hard copy`_-like documents from Discourse content easily.
 
 It aims to make documentation generation effortless.
 
 There might still be dragons.
 
-
+.. _hard copy: https://en.wikipedia.org/wiki/Hard_copy
 
 *******
 Install
@@ -66,17 +66,17 @@ Synopsis
 Features
 ********
 All output formats are provided by pandoc fame. These have been tested:
-- pdf, docx, odt, pptx, epub2, epub3, fb2, latex, texinfo, html, html5
+pdf, docx, odt, pptx, epub2, epub3, fb2, latex, texinfo, html, html5, json, plain, rtf, revealjs, s5.
 
 
 *******
 Credits
 *******
-- `Donald Knuth`_ and the `LaTeX Team`_ for conceiving and maintaining TeX and LaTeX
-- `John MacFarlane`_ and all contributors for creating and curating pandoc_
-- The amazing `Discourse Team`_ and all contributors for creating Discourse and its spirit
+- `Donald Knuth`_ and the `LaTeX Team`_ for conceiving and maintaining TeX and LaTeX.
+- `John MacFarlane`_ and all contributors for creating and curating pandoc_.
+- The amazing `Discourse Team`_ and all contributors for creating Discourse and its spirit.
 
-Thanks!
+You know how you are. Thanks!
 
 
 **************

discodoc/__init__.py

@@ -1,3 +1,3 @@
-"""discodoc creates documents from Discourse content easily"""
+"""discodoc - create hardcopy-like documents from Discourse content easily"""
 __appname__ = 'discodoc'
 __version__ = '0.1.0'

discodoc/cli.py

@@ -14,12 +14,12 @@
 
 def run():
     """
-    discodoc creates documents from Discourse content easily
+    discodoc - create hardcopy-like documents from Discourse content easily
 
     Usage:
-      vasuki <url> [--format=<format>] [--path=<output-path>] [--debug]
-      vasuki --version
-      vasuki (-h | --help)
+      discodoc <url> [--format=<format>] [--path=<output-path>] [--debug]
+      discodoc --version
+      discodoc (-h | --help)
 
     Options:
       --format=<format>                 Output format.

discodoc/core.py

@@ -19,18 +19,16 @@ def __init__(self, options):
 
     def run(self):
 
+        # Run sanity checks and apply defaults.
+
         if self.options.path is None:
             self.options.path = os.getcwd()
 
         if not os.path.isdir(self.options.path):
             raise KeyError('Output directory "{}" does not exist'.format(self.options.path))
 
-        # Unique identifier generators
-        #if self.options.format == 'pdf':
         discourse_to_document(self.options.url, format=self.options.format, output_path=self.options.path)
 
-        #else:
-        #    raise KeyError('Output format "{}" not implemented'.format(self.options.format))
 
 
 def discourse_to_document(url, format=None, output_path=None):

doc/backlog.rst

@@ -7,18 +7,24 @@ Prio 1
 - [x] Obtain output format from commandline
 - [x] Check paging re. multiple posts
 - [o] Resolve format <=> formatter intertwingulation
+- [o] Slides: beamer, reveal.js
 - [o] Multi-topic acquisition
 - [o] Obtain title from command line
-- [o] Slides: beamer, reveal.js
 
 Prio 2
 ======
 - [o] Obtain and propagate metadata suitable for pandoc from Discourse
 - [o] Obtain and propagate more Discourse topic metadata into document (visually and metadata)
 - [o] Obtain PANDOC_OPTIONS from environment
-- [o] Select specific posts
 - [o] Topic download progress bar
+- [o] Select specific posts per single topic
+- [o] Select specific posts across multiple topics
+
+Prio 3
+======
 - [o] Select style: document, conversation, etc.
 - [o] Style "conversation"
     - Print author names and post metadata
     - Add separators between single posts
+- [o] Currently, fetching is limited to 1000 posts per topic.
+  Fetch all posts by iterating through them, see https://github.com/pfaffman/discourse-downloader/blob/7be37ea26eb1d81a961a085a126e09c7a8d4a7cf/discourse-downloader#L111

doc/research.rst

@@ -0,0 +1,30 @@
+#################
+discodoc research
+#################
+
+Hard copy rendering
+===================
+- https://meta.discourse.org/t/format-for-hard-copy-or-pdf-printing/13033
+- https://meta.discourse.org/t/pocket-offline-reader-support/17500
+- https://meta.discourse.org/t/printer-friendly-css/30899
+- https://meta.discourse.org/t/add-a-get-option-to-enable-noscript-view-of-a-page/33823
+- https://meta.discourse.org/t/print-long-topic-to-pdf-redux-again/44639
+- https://meta.discourse.org/t/making-doi-ready-pdfs-from-discourse/92858
+- https://meta.discourse.org/t/converting-links-from-raw-markdown-to-html/102422
+- https://meta.discourse.org/t/creating-an-offline-topic-reading-archive/103651
+
+Pagination and more
+===================
+- https://meta.discourse.org/t/paginating-api-search-results/49066
+- https://meta.discourse.org/t/api-to-fetch-topic-by-page/63342/2
+- https://meta.discourse.org/t/struggling-with-pagination-within-search-query-json/59558
+- https://blog.codinghorror.com/the-end-of-pagination/
+- Why not to use infinite scroll on your website
+  https://news.ycombinator.com/item?id=7559737
+
+Discourse API
+=============
+- https://meta.discourse.org/t/discourse-api-documentation/22706
+- https://meta.discourse.org/t/api-can-i-authenticate-without-putting-the-key-in-the-url/29425
+- https://meta.discourse.org/t/global-rate-limits-and-throttling-in-discourse/78612
+- https://meta.discourse.org/t/changing-removing-api-rate-limit-with-category-creation/78611

setup.py

@@ -7,7 +7,7 @@
 
 setup(name='discodoc',
       version='0.1.0',
-      description='Create documents from Discourse content easily',
+      description='Create hardcopy-like documents from Discourse content easily',
       long_description=README,
       license="AGPL 3, EUPL 1.2",
       classifiers=[