Fix document for Kindle and add description about kindlegen

CHANGES

@@ -111,6 +111,7 @@ Features added
 * #2892: Added ``-a`` (``--append-syspath``) option to ``sphinx-apidoc``
 * #1604: epub3 builder: Obey font-related CSS when viewing in iBooks.
 * #646: ``option`` directive support '.' character as a part of options
+* Add document about kindlegen and fix document structure for it.
 
 Bugs fixed
 ----------

doc/ext/builtins.rst

@@ -0,0 +1,24 @@
+Builtin Sphinx extensions
+-------------------------
+
+These extensions are built in and can be activated by respective entries in the
+:confval:`extensions` configuration value:
+
+.. toctree::
+
+   autodoc
+   autosectionlabel
+   autosummary
+   coverage
+   doctest
+   extlinks
+   githubpages
+   graphviz
+   ifconfig
+   inheritance
+   intersphinx
+   linkcode
+   math
+   napoleon
+   todo
+   viewcode

doc/ext/thirdparty.rst

@@ -0,0 +1,35 @@
+Third-party extensions
+----------------------
+
+You can find several extensions contributed by users in the `Sphinx Contrib`_
+repository.  It is open for anyone who wants to maintain an extension
+publicly; just send a short message asking for write permissions.
+
+There are also several extensions hosted elsewhere.  The `Sphinx extension
+survey <http://sphinxext-survey.readthedocs.org/en/latest/>`__ contains a
+comprehensive list.
+
+If you write an extension that you think others will find useful or you think
+should be included as a part of Sphinx, please write to the project mailing
+list (`join here <https://groups.google.com/forum/#!forum/sphinx-dev>`_).
+
+.. _Sphinx Contrib: https://bitbucket.org/birkenfeld/sphinx-contrib
+
+
+Where to put your own extensions?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Extensions local to a project should be put within the project's directory
+structure.  Set Python's module search path, ``sys.path``, accordingly so that
+Sphinx can find them.
+E.g., if your extension ``foo.py`` lies in the ``exts`` subdirectory of the
+project root, put into :file:`conf.py`::
+
+   import sys, os
+
+   sys.path.append(os.path.abspath('exts'))
+
+   extensions = ['foo']
+
+You can also install extensions anywhere else on ``sys.path``, e.g. in the
+``site-packages`` directory.

doc/extensions.rst

@@ -10,64 +10,7 @@ any aspect of document processing.
 This chapter describes the extensions bundled with Sphinx.  For the API
 documentation on writing your own extension, see :ref:`dev-extensions`.
 
-Builtin Sphinx extensions
--------------------------
-
-These extensions are built in and can be activated by respective entries in the
-:confval:`extensions` configuration value:
-
 .. toctree::
 
-   ext/autodoc
+   ext/builtins
-   ext/autosectionlabel
+   ext/thirdparty
-   ext/autosummary
-   ext/coverage
-   ext/doctest
-   ext/extlinks
-   ext/githubpages
-   ext/graphviz
-   ext/ifconfig
-   ext/inheritance
-   ext/intersphinx
-   ext/linkcode
-   ext/math
-   ext/napoleon
-   ext/todo
-   ext/viewcode
-
-
-Third-party extensions
-----------------------
-
-You can find several extensions contributed by users in the `Sphinx Contrib`_
-repository.  It is open for anyone who wants to maintain an extension
-publicly; just send a short message asking for write permissions.
-
-There are also several extensions hosted elsewhere.  The `Sphinx extension
-survey <http://sphinxext-survey.readthedocs.org/en/latest/>`__ contains a
-comprehensive list.
-
-If you write an extension that you think others will find useful or you think
-should be included as a part of Sphinx, please write to the project mailing
-list (`join here <https://groups.google.com/forum/#!forum/sphinx-dev>`_).
-
-.. _Sphinx Contrib: https://bitbucket.org/birkenfeld/sphinx-contrib
-
-
-Where to put your own extensions?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Extensions local to a project should be put within the project's directory
-structure.  Set Python's module search path, ``sys.path``, accordingly so that
-Sphinx can find them.
-E.g., if your extension ``foo.py`` lies in the ``exts`` subdirectory of the
-project root, put into :file:`conf.py`::
-
-   import sys, os
-
-   sys.path.append(os.path.abspath('exts'))
-
-   extensions = ['foo']
-
-You can also install extensions anywhere else on ``sys.path``, e.g. in the
-``site-packages`` directory.

doc/faq.rst

@@ -167,11 +167,45 @@ The following list gives some hints for the creation of epub files:
   :confval:`html_static_path` directory and reference it with its full path in
   the :confval:`epub_cover` config option.
 
+* kindlegen_ command can convert from epub3 resulting file to ``.mobi`` file
+  for Kindle. You can get ``yourdoc.mobi`` under ``_build/epub`` after the
+  following command:
+
+  .. code-block:: bash
+
+     $ make epub
+     $ kindlegen _build/epub/yourdoc.epub
+
+  kindlegen commands doesn't accept documents that have section
+  titles surrounding ``toctree`` directive:
+
+  .. code-block:: rst
+
+     Section Title
+     =============
+
+     .. toctree::
+
+        subdocument
+
+     Section After Toc Tree
+     ======================
+
+  kindlegen assumes all documents order in line, but resulting document
+  has complecated order for kindlegen::
+
+     ``parent.xhtml`` -> ``child.xhtml`` -> ``parent.xhtml``
+
+  If you got the following error, fix document structure::
+
+     Error(prcgen):E24011: TOC section scope is not included in the parent chapter:(title)
+     Error(prcgen):E24001: The table of content could not be built.
+
 .. _Epubcheck: https://code.google.com/archive/p/epubcheck
 .. _Calibre: http://calibre-ebook.com/
 .. _FBreader: https://fbreader.org/
 .. _Bookworm: http://www.oreilly.com/bookworm/index.html
-
+.. _kindlegen: https://www.amazon.com/gp/feature.html?docId=1000765211
 
 .. _texinfo-faq: