automate more documentation

.readme.rst

@@ -308,92 +308,39 @@ Returns
 .. code:: python
 
       def update(self, n=1):
-          """
-          Manually update the progress bar, useful for streams
-          such as reading files.
-          E.g.:
-          >>> t = tqdm(total=filesize) # Initialise
-          >>> for current_buffer in stream:
-          ...    ...
-          ...    t.update(len(current_buffer))
-          >>> t.close()
-          The last line is highly recommended, but possibly not necessary if
-          ``t.update()`` will be called in such a way that ``filesize`` will be
-          exactly reached and printed.
-
-          Parameters
-          ----------
-          n  : int, optional
-              Increment to add to the internal counter of iterations
-              [default: 1].
-          """
+          """{DOC_tqdm.tqdm.update}"""
 
       def close(self):
-          """Cleanup and (if leave=False) close the progressbar."""
+          """{DOC_tqdm.tqdm.close}"""
 
       def clear(self, nomove=False):
-          """Clear current bar display."""
+          """{DOC_tqdm.tqdm.clear}"""
 
       def refresh(self):
-          """Force refresh the display of this bar."""
+          """{DOC_tqdm.tqdm.refresh}"""
 
       def unpause(self):
-          """Restart tqdm timer from last print time."""
+          """{DOC_tqdm.tqdm.unpause}"""
 
       def reset(self, total=None):
-          """
-          Resets to 0 iterations for repeated use.
-
-          Consider combining with ``leave=True``.
-
-          Parameters
-          ----------
-          total  : int, optional. Total to use for the new bar.
-          """
+          """{DOC_tqdm.tqdm.reset}"""
 
       def set_description(self, desc=None, refresh=True):
-          """
-          Set/modify description of the progress bar.
-
-          Parameters
-          ----------
-          desc  : str, optional
-          refresh  : bool, optional
-              Forces refresh [default: True].
-          """
+          """{DOC_tqdm.tqdm.set_description}"""
 
       def set_postfix(self, ordered_dict=None, refresh=True, **kwargs):
-          """
-          Set/modify postfix (additional stats)
-          with automatic formatting based on datatype.
-
-          Parameters
-          ----------
-          refresh  : bool, optional
-              Forces refresh [default: True].
-          """
+          """{DOC_tqdm.tqdm.set_postfix}"""
 
       @classmethod
       def write(cls, s, file=sys.stdout, end="\n"):
-          """Print a message via tqdm (without overlap with bars)."""
+          """{DOC_tqdm.tqdm.write}"""
 
       @property
       def format_dict(self):
-          """Public API for read-only member access."""
+          """{DOC_tqdm.tqdm.format_dict}"""
 
       def display(self, msg=None, pos=None):
-          """
-          Use ``self.sp`` to display ``msg`` in the specified ``pos``.
-
-          Consider overloading this function when inheriting to use e.g.:
-          ``self.some_frontend(**self.format_dict)`` instead of ``self.sp``.
-
-          Parameters
-          ----------
-          msg  : str, optional. What to display (default: ``repr(self)``).
-          pos  : int, optional. Position to ``moveto``
-            (default: ``abs(self.pos)``).
-          """
+          """{DOC_tqdm.tqdm.display}"""
 
     def trange(*args, **kwargs):
         """

README.rst

@@ -478,8 +478,10 @@ Returns
 
           Parameters
           ----------
+          ordered_dict  : dict or OrderedDict, optional
           refresh  : bool, optional
               Forces refresh [default: True].
+          kwargs  : dict, optional
           """
 
       @classmethod

mkdocs.py

@@ -20,14 +20,20 @@
 """
 
 
-def doc2rst(doc, arglist=True):
+def doc2rst(doc, arglist=True, raw=False):
     """
     arglist  : bool, whether to create argument lists
+    raw  : bool, ignores arglist and indents by 2 spaces
     """
-    doc = dedent(doc).replace('`', '``')
-    if arglist:
-        doc = '\n'.join([i if not i or i[0] == ' ' else '* ' + i + '  '
-                         for i in doc.split('\n')])
+    doc = doc.replace('`', '``')
+    if raw:
+        doc = doc.replace('\n ', '\n   ')
+        #doc = '\n'.join(i.rstrip() for i in doc.split('\n'))
+    else:
+        doc = dedent(doc)
+        if arglist:
+            doc = '\n'.join([i if not i or i[0] == ' ' else '* ' + i + '  '
+                             for i in doc.split('\n')])
     return doc
 
 
@@ -42,6 +48,11 @@ def doc2rst(doc, arglist=True):
 DOC_tqdm_init_args, _, DOC_tqdm_init_rets = DOC_tqdm_init_args\
     .partition(doc2rst(HEAD_RETS))
 DOC_cli = doc2rst(tqdm._main.CLI_EXTRA_DOC).partition(doc2rst(HEAD_CLI))[-1]
+DOC_tqdm_tqdm = {}
+for i in dir(tqdm.tqdm):
+    doc = getattr(tqdm.tqdm, i).__doc__
+    if doc:
+        DOC_tqdm_tqdm[i] = doc2rst(doc, raw=True)
 
 # special cases
 DOC_tqdm_init_args = DOC_tqdm_init_args.replace(' *,', ' ``*``,')
@@ -51,6 +62,8 @@ def doc2rst(doc, arglist=True):
     .replace('{DOC_tqdm.tqdm.__init__.Parameters}', DOC_tqdm_init_args)\
     .replace('{DOC_tqdm._main.CLI_EXTRA_DOC}', DOC_cli)\
     .replace('{DOC_tqdm.tqdm.__init__.Returns}', DOC_tqdm_init_rets)
+for k, v in DOC_tqdm_tqdm.items():
+    README_rst = README_rst.replace('{DOC_tqdm.tqdm.%s}' % k, v)
 
 if __name__ == "__main__":
     fndoc = path.join(src_dir, 'README.rst')