Fixed toc and link errors for epub build (Issue cakephp#1126). Add co…

…ver to epub. * The epub build is derived from the html build in sphinx; however, some sections, such as "Welcome" don't make sense to include in the epub. Essentially, this means that the epub needs it's own toc file which is what this commit adds (epub-contents.rst). Since there's no epub_ type option to override the master_doc var, this has to be done as an arg to sphinx-build. * This commit also adds a cover to the epub so it looks more like a real book. The cover isn't great but at least the framework will be there for someone to add a real cover image.
ekos · Mar 4, 2014 · 3913959 · 3913959
1 parent ce99b33
commit 3913959
Show file tree

Hide file tree

Showing 23 changed files with 218 additions and 23 deletions.
diff --git a/config/all.py b/config/all.py
@@ -248,19 +248,22 @@
 
 epub_theme = 'cakephp-epub'
 
+# The cover page information.
+epub_cover = ('_static/epub-logo.png', 'epub-cover.html')
+
 # The language of the text. It defaults to the language option
 # or en if the language is not set.
 #epub_language = ''
 
 # The scheme of the identifier. Typical schemes are ISBN or URL.
-#epub_scheme = ''
+epub_scheme = 'URL'
 
 # The unique identifier of the text. This can be a ISBN number
 # or the project homepage.
-#epub_identifier = ''
+epub_identifier = 'http://cakephp.org'
 
 # A unique identification for the text.
-#epub_uid = ''
+epub_uid = 'cakephpcookbook1393624653'
 
 # HTML files that should be inserted before the pages created by sphinx.
 # The format is a list of tuples containing the path and title.
@@ -275,6 +278,7 @@
     'index.html',
     'pdf-contents.html',
     'search.html',
+    'contents.html'
 ]
 
 # The depth of the table of contents in toc.ncx.
@@ -283,6 +287,9 @@
 # Allow duplicate toc entries.
 epub_tocdup = False
 
+# If true, add an index to the epub document.
+epub_use_index = False
+
 # Languages available.
 languages = ['en', 'pt', 'es', 'ja', 'ru', 'fr']
 

diff --git a/en/Makefile b/en/Makefile
@@ -88,7 +88,7 @@ devhelp:
 	@echo "# devhelp"
 
 epub:
-	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub/$(LANG)
+	$(SPHINXBUILD) -b epub -D master_doc='epub-contents' $(ALLSPHINXOPTS) $(BUILDDIR)/epub/$(LANG)
 	@echo
 	@echo "Build finished. The epub file is in $(BUILDDIR)/epub/$(LANG)."
 

diff --git a/en/core-libraries/behaviors/containable.rst b/en/core-libraries/behaviors/containable.rst
@@ -376,6 +376,8 @@ model, you don't need to use 'contain' again for related models
     all models used in containment, you may consider attaching it to
     your AppModel.
 
+.. _containablebehavior-options:
+
 ContainableBehavior options
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -428,7 +430,7 @@ Here's an example of how to contain associations when paginating::
 .. note::
 
     If you contained the associations through the model instead,
-    it will not honor Containable's :ref:`recursive option <containableBehavior-options>`.
+    it will not honor Containable's :ref:`recursive option <containablebehavior-options>`.
     So if you set recursive to -1 for example for the model, it won't work::
 
         $this->User->recursive = -1;

diff --git a/en/core-libraries/global-constants-and-functions.rst b/en/core-libraries/global-constants-and-functions.rst
@@ -126,7 +126,7 @@ such as debugging and translating content.
     If ``$showHTML`` is true or left as null, the data is rendered to be
     browser-friendly.
     If $showFrom is not set to false, the debug output will start with the line from
-    which it was called
+    which it was called.
     Also see :doc:`/development/debugging`
 
 .. php:function:: env(string $key)

diff --git a/en/core-libraries/helpers/form.rst b/en/core-libraries/helpers/form.rst
@@ -950,7 +950,7 @@ Datetime options
 Form Element-Specific Methods
 =============================
 
- All elements are created under a form for the ``User`` model as in the examples above.
+All elements are created under a form for the ``User`` model as in the examples above.
 For this reason, the HTML code generated will contain attributes that reference to the User model.
 Ex: name=data[User][username], id=UserUsername
 
@@ -1057,6 +1057,7 @@ Ex: name=data[User][username], id=UserUsername
     generated. Example:
 
     .. code-block:: html
+
         <textarea name="data[User][notes]" id="UserNotes">
         This text is to be edited.
         </textarea>

diff --git a/en/epub-contents.rst b/en/epub-contents.rst
@@ -0,0 +1,26 @@
+Contents
+########
+
+.. toctree::
+   :maxdepth: 3
+
+   installation
+   getting-started
+   cakephp-overview
+   controllers
+   views
+   models
+   core-libraries
+   plugins
+   console-and-shells
+   development
+   deployment
+   tutorials-and-examples
+   contributing
+   appendices
+
+.. todolist::
+
+.. meta::
+    :title lang=en: Contents
+    :keywords lang=en: core libraries,ref search,shells,deployment,appendices,glossary,models
diff --git a/en/models/datasources.rst b/en/models/datasources.rst
@@ -311,9 +311,9 @@ So if the Sqlserver Datasource errors out with::
     Error: Database connection "Sqlserver" is missing, or could not be created.
 
 First check if the SQL Server PHP extension pdo_sqlsrv and the SQL Server Native
-Client.
+Client are installed properly.
 
 .. meta::
     :title lang=en: DataSources
     :keywords lang=en: array values,model fields,connection configuration,implementation details,relational databases,best bet,mysql postgresql,sqlite,external sources,ldap server,database connection,rdbms,sqlserver,postgres,relational database,mssql,aggregates,apis,repository,signatures
-Client are installed properly.
+
diff --git a/es/Makefile b/es/Makefile
@@ -7,7 +7,7 @@ SPHINXBUILD   = sphinx-build
 PAPER         =
 BUILDDIR      = ../build
 PYTHON        = python
-LANG          = es
+LANG          = en
 
 # Internal variables.
 PAPEROPT_a4     = -D latex_paper_size=a4
@@ -88,7 +88,7 @@ devhelp:
 	@echo "# devhelp"
 
 epub:
-	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub/$(LANG)
+	$(SPHINXBUILD) -b epub -D master_doc='epub-contents' $(ALLSPHINXOPTS) $(BUILDDIR)/epub/$(LANG)
 	@echo
 	@echo "Build finished. The epub file is in $(BUILDDIR)/epub/$(LANG)."
 

diff --git a/es/epub-contents.rst b/es/epub-contents.rst
@@ -0,0 +1,13 @@
+Contents
+########
+
+.. toctree::
+   :maxdepth: 3
+
+   installation
+   getting-started
+   cakephp-overview
+   tutorials-and-examples
+
+.. todolist::
+
diff --git a/fr/Makefile b/fr/Makefile
@@ -7,7 +7,7 @@ SPHINXBUILD   = sphinx-build
 PAPER         =
 BUILDDIR      = ../build
 PYTHON        = python
-LANG          = fr
+LANG          = en
 
 # Internal variables.
 PAPEROPT_a4     = -D latex_paper_size=a4
@@ -88,7 +88,7 @@ devhelp:
 	@echo "# devhelp"
 
 epub:
-	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub/$(LANG)
+	$(SPHINXBUILD) -b epub -D master_doc='epub-contents' $(ALLSPHINXOPTS) $(BUILDDIR)/epub/$(LANG)
 	@echo
 	@echo "Build finished. The epub file is in $(BUILDDIR)/epub/$(LANG)."
 

diff --git a/fr/epub-contents.rst b/fr/epub-contents.rst
@@ -0,0 +1,26 @@
+Contenu
+#######
+
+.. toctree::
+   :maxdepth: 3
+
+   installation
+   getting-started
+   cakephp-overview
+   controllers
+   views
+   models
+   core-libraries
+   plugins
+   console-and-shells
+   development
+   deployment
+   tutorials-and-examples
+   contributing
+   appendices
+
+.. todolist::
+
+.. meta::
+    :title lang=fr: Contents
+    :keywords lang=fr: librairies du coeur,ref search,shells,déploiement,appendices,glossary,models
diff --git a/ja/Makefile b/ja/Makefile
@@ -7,7 +7,7 @@ SPHINXBUILD   = sphinx-build
 PAPER         =
 BUILDDIR      = ../build
 PYTHON        = python
-LANG          = ja
+LANG          = en
 
 # Internal variables.
 PAPEROPT_a4     = -D latex_paper_size=a4
@@ -88,7 +88,7 @@ devhelp:
 	@echo "# devhelp"
 
 epub:
-	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub/$(LANG)
+	$(SPHINXBUILD) -b epub -D master_doc='epub-contents' $(ALLSPHINXOPTS) $(BUILDDIR)/epub/$(LANG)
 	@echo
 	@echo "Build finished. The epub file is in $(BUILDDIR)/epub/$(LANG)."
 

diff --git a/ja/epub-contents.rst b/ja/epub-contents.rst
@@ -0,0 +1,23 @@
+コンテンツ
+##########
+
+.. toctree::
+   :maxdepth: 3
+
+   installation
+   getting-started
+   cakephp-overview
+   controllers
+   views
+   models
+   core-libraries
+   plugins
+   console-and-shells
+   development
+   deployment
+   tutorials-and-examples
+   contributing
+   appendices
+
+.. todolist::
+
diff --git a/pt/Makefile b/pt/Makefile
@@ -7,7 +7,7 @@ SPHINXBUILD   = sphinx-build
 PAPER         =
 BUILDDIR      = ../build
 PYTHON        = python
-LANG          = pt
+LANG          = en
 
 # Internal variables.
 PAPEROPT_a4     = -D latex_paper_size=a4
@@ -88,7 +88,7 @@ devhelp:
 	@echo "# devhelp"
 
 epub:
-	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub/$(LANG)
+	$(SPHINXBUILD) -b epub -D master_doc='epub-contents' $(ALLSPHINXOPTS) $(BUILDDIR)/epub/$(LANG)
 	@echo
 	@echo "Build finished. The epub file is in $(BUILDDIR)/epub/$(LANG)."
 

diff --git a/pt/epub-contents.rst b/pt/epub-contents.rst
@@ -0,0 +1,23 @@
+Contents
+########
+
+.. toctree::
+   :maxdepth: 3
+
+   installation
+   getting-started
+   cakephp-overview
+   controllers
+   views
+   models
+   core-libraries
+   plugins
+   console-and-shells
+   development
+   deployment
+   tutorials-and-examples
+   contributing
+   appendices
+
+.. todolist::
+
diff --git a/ro/Makefile b/ro/Makefile
@@ -7,7 +7,7 @@ SPHINXBUILD   = sphinx-build
 PAPER         =
 BUILDDIR      = ../build
 PYTHON        = python
-LANG          = ro
+LANG          = en
 
 # Internal variables.
 PAPEROPT_a4     = -D latex_paper_size=a4
@@ -88,7 +88,7 @@ devhelp:
 	@echo "# devhelp"
 
 epub:
-	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub/$(LANG)
+	$(SPHINXBUILD) -b epub -D master_doc='epub-contents' $(ALLSPHINXOPTS) $(BUILDDIR)/epub/$(LANG)
 	@echo
 	@echo "Build finished. The epub file is in $(BUILDDIR)/epub/$(LANG)."
 

diff --git a/ro/epub-contents.rst b/ro/epub-contents.rst
@@ -0,0 +1,9 @@
+Cuprins
+#######
+
+.. toctree::
+    :maxdepth: 3
+
+    index
+
+.. todolist::
diff --git a/ru/Makefile b/ru/Makefile
@@ -7,7 +7,7 @@ SPHINXBUILD   = sphinx-build
 PAPER         =
 BUILDDIR      = ../build
 PYTHON        = python
-LANG          = ru
+LANG          = en
 
 # Internal variables.
 PAPEROPT_a4     = -D latex_paper_size=a4
@@ -88,7 +88,7 @@ devhelp:
 	@echo "# devhelp"
 
 epub:
-	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub/$(LANG)
+	$(SPHINXBUILD) -b epub -D master_doc='epub-contents' $(ALLSPHINXOPTS) $(BUILDDIR)/epub/$(LANG)
 	@echo
 	@echo "Build finished. The epub file is in $(BUILDDIR)/epub/$(LANG)."
 

diff --git a/ru/epub-contents.rst b/ru/epub-contents.rst
@@ -0,0 +1,23 @@
+Содержание
+##########
+
+.. toctree::
+   :maxdepth: 3
+
+   installation
+   getting-started
+   cakephp-overview
+   controllers
+   views
+   models
+   core-libraries
+   plugins
+   console-and-shells
+   development
+   deployment
+   tutorials-and-examples
+   contributing
+   appendices
+
+.. todolist::
+
diff --git a/sr/Makefile b/sr/Makefile
@@ -7,7 +7,7 @@ SPHINXBUILD   = sphinx-build
 PAPER         =
 BUILDDIR      = ../build
 PYTHON        = python
-LANG          = sr
+LANG          = en
 
 # Internal variables.
 PAPEROPT_a4     = -D latex_paper_size=a4
@@ -88,7 +88,7 @@ devhelp:
 	@echo "# devhelp"
 
 epub:
-	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub/$(LANG)
+	$(SPHINXBUILD) -b epub -D master_doc='epub-contents' $(ALLSPHINXOPTS) $(BUILDDIR)/epub/$(LANG)
 	@echo
 	@echo "Build finished. The epub file is in $(BUILDDIR)/epub/$(LANG)."
 

diff --git a/sr/epub-contents.rst b/sr/epub-contents.rst
@@ -0,0 +1,9 @@
+Contents
+########
+
+.. toctree::
+    :maxdepth: 3
+
+    index
+
+.. todolist::