From 774c7603d084f1bee0def9e0148dea9a015ee018 Mon Sep 17 00:00:00 2001
From: Kovid Goyal <kovid@kovidgoyal.net>
Date: Sat, 5 Jul 2014 09:10:12 +0530
Subject: [PATCH] More API documentation

---
 manual/develop.rst                       |  9 +++++++--
 manual/polish.rst                        | 12 +++++++++++-
 src/calibre/ebooks/oeb/polish/replace.py | 20 +++++++++++++++++++-
 3 files changed, 37 insertions(+), 4 deletions(-)

diff --git a/manual/develop.rst b/manual/develop.rst
index d07c9f72c7..c1ca129d6f 100644
--- a/manual/develop.rst
+++ b/manual/develop.rst
@@ -397,9 +397,14 @@ you can also directly import |app|, as follows::
 It is essential that you import the init_calibre module before any other |app| modules/packages as
 it sets up the interpreter to run |app| code.
 
-.. toctree::
-    :hidden:
+API documentation for various parts of |app|
+------------------------------------------------
 
+.. toctree::
+    :maxdepth: 1
+
+    news_recipe
+    plugins
     db_api
     polish
 
diff --git a/manual/polish.rst b/manual/polish.rst
index 12e6d8d647..641e84536b 100644
--- a/manual/polish.rst
+++ b/manual/polish.rst
@@ -26,7 +26,7 @@ for the book being edited like this::
     from calibre.gui2.tweak_book import current_container
     container = current_container()
     if container is None:
-        # No book has been opened yet
+        report_error # No book has been opened yet
 
 
 The Container object
@@ -35,4 +35,14 @@ The Container object
 .. autoclass:: Container
    :members:
 
+Tools for dealing with component files in a container
+--------------------------------------------------------
+
+.. module:: calibre.ebooks.oeb.polish.replace
+
+.. autofunction:: replace_links
+
+.. autofunction:: rename_files
+
+.. autofunction:: get_recommended_folders
 
diff --git a/src/calibre/ebooks/oeb/polish/replace.py b/src/calibre/ebooks/oeb/polish/replace.py
index 2843f06342..1278c4146d 100644
--- a/src/calibre/ebooks/oeb/polish/replace.py
+++ b/src/calibre/ebooks/oeb/polish/replace.py
@@ -72,6 +72,16 @@ class LinkRebaser(object):
 
 
 def replace_links(container, link_map, frag_map=lambda name, frag:frag, replace_in_opf=False):
+    '''
+    Replace links to files in the container. Will iterate over all files in the container and change the specified links in them.
+
+    :param link_map: A mapping of old canonical name to new canonical name. For example: :code:`{'images/old.png': 'images/new.png'}`
+    :param frag_map: A callable that takes two arguments ``(name, anchor)`` and
+        returns a new anchor. This is useful if you need to change the anchors in
+        HTML files. By default, it does nothing.
+    :param replace_in_opf: If False, links are not replaced in the OPF file.
+
+    '''
     for name, media_type in container.mime_map.iteritems():
         if name == container.opf_name and not replace_in_opf:
             continue
@@ -107,6 +117,12 @@ def smarten_punctuation(container, report):
     return smartened
 
 def rename_files(container, file_map):
+    '''
+    Rename files in the container, automatically updating all links to them.
+
+    :param file_map: A mapping of old canonical name to new canonical name, for
+        example: :code:`{'text/chapter1.html': 'chapter1.html'}`.
+    '''
     overlap = set(file_map).intersection(set(file_map.itervalues()))
     if overlap:
         raise ValueError('Circular rename detected. The files %s are both rename targets and destinations' % ', '.join(overlap))
@@ -166,7 +182,9 @@ def mt_to_category(container, mt):
     return category
 
 def get_recommended_folders(container, names):
-    ' Return the folders that are recommended for the given filenames '
+    ''' Return the folders that are recommended for the given filenames. The
+    recommendation is based on where the majority of files of the same type are
+    located in the container. '''
     from calibre.ebooks.oeb.polish.utils import guess_type
     counts = defaultdict(Counter)
     for name, mt in container.mime_map.iteritems():