diff --git a/CHANGES b/CHANGES index 58d92742e..1fa52a255 100644 --- a/CHANGES +++ b/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 ---------- diff --git a/doc/ext/builtins.rst b/doc/ext/builtins.rst new file mode 100644 index 000000000..6d5e59a89 --- /dev/null +++ b/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 diff --git a/doc/ext/thirdparty.rst b/doc/ext/thirdparty.rst new file mode 100644 index 000000000..6304e4af3 --- /dev/null +++ b/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 `__ 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 `_). + +.. _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. diff --git a/doc/extensions.rst b/doc/extensions.rst index f58361eb1..afd211c34 100644 --- a/doc/extensions.rst +++ b/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/autosectionlabel - 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 `__ 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 `_). - -.. _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. + ext/builtins + ext/thirdparty diff --git a/doc/faq.rst b/doc/faq.rst index 04bd05717..5e74f48d4 100644 --- a/doc/faq.rst +++ b/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: