diff --git a/Makefile b/Makefile index e6fce5323683255b80749cd4fe08b15e257475ee..a137eae166a522c4a010687c81ae5260d8fbea1b 100644 --- a/Makefile +++ b/Makefile @@ -8,10 +8,10 @@ ES_HOST = .PHONY: all clean html latexpdf epub htmlhelp website website-dirs # Languages that can be built. -LANGS = en es fr ja pt ru +LANGS = en es fr ja pt ru ro sr # pdflatex does not like ja or ru for some reason. -PDF_LANGS = en es fr pt +PDF_LANGS = en es fr pt ro sr DEST = website diff --git a/README.mdown b/README.mdown index f83c0df655a8dd3b1cdf13bde31804e559c32800..b29e4a2a816bf7508dd727dbd4784d1c337c0ea6 100644 --- a/README.mdown +++ b/README.mdown @@ -1,7 +1,7 @@ CakePHP Documentation ===================== -This documentation is planned to replace the existing cookbook. Hopefully enabling community contributions and enabling multiple format documentation generation. +This is the official documentation for the CakePHP project. It is available online in HTML, PDF and EPUB formats at http://book.cakephp.org. Requirements ------------ @@ -43,10 +43,21 @@ After installing the required packages, you can build the documentation using `M # Populate the search index make populate-index -This will generate all the documentation in an html form. Other output such as 'pdf' and 'htmlhelp' are not fully complete at this time. +This will generate all the documentation in an html form. Other output such as 'htmlhelp' are not fully complete at this time. After making changes to the documentation, you can build the html version of the docs by using `make html` again. This will build only the html files that have had changes made to them. +Building the PDF +---------------- + +Building the PDF is a non-trivial task. + +1. Install Latex - This varies by distribution/OS so refer to your package manager. You should install the full LaTeX package. The basic one requires many additional packages to be installed with `tlmgr` +2. Run `make latex-en`. +3. Run `make pdf-en`. + +At this point the completed PDF should be in build/latex/en/CakePHPCookbook.pdf. + Contributing ------------ @@ -90,4 +101,3 @@ Making search work locally * Populate the search index using `make populate-index`. * You should now be able to search the docs using elasticsearch. - diff --git a/config/all.py b/config/all.py index 66202f7809a43d6f24433086d594965338446fa7..e9b95b86da63c9567f2051042135b9d44a5291b9 100644 --- a/config/all.py +++ b/config/all.py @@ -251,19 +251,22 @@ epub_copyright = u'2013, Cake Software Foundation, Inc.' 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. @@ -278,6 +281,7 @@ epub_exclude_files = [ 'index.html', 'pdf-contents.html', 'search.html', + 'contents.html' ] # The depth of the table of contents in toc.ncx. @@ -286,6 +290,9 @@ epub_tocdepth = 2 # 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 index fb7ef46082a021074e56a759f5ddd22b497d007b..9d2fee1833a1bd9b91ab721e022d48aa7a39a269 100644 --- 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/appendices/glossary.rst b/en/appendices/glossary.rst index a1a88280bedcd93676051d6b29836ad8bb8d7f00..e713b9774803f594677ca73ecd63e21c29a8cabb 100644 --- a/en/appendices/glossary.rst +++ b/en/appendices/glossary.rst @@ -6,27 +6,27 @@ Glossary routing array An array of attributes that are passed to :php:meth:`Router::url()`. They typically look like:: - + array('controller' => 'posts', 'action' => 'view', 5) HTML attributes An array of key => values that are composed into HTML attributes. For example:: - + // Given array('class' => 'my-class', 'target' => '_blank') // Would generate class="my-class" target="_blank" - If an option can be minimized or accepts it's name as the value, then ``true`` + If an option can be minimized or accepts it's name as the value, then ``true`` can be used:: - + // Given array('checked' => true) - + // Would generate checked="checked" - + plugin syntax Plugin syntax refers to the dot separated class name indicating classes are part of a plugin. E.g. ``DebugKit.Toolbar`` The plugin is DebugKit, @@ -60,7 +60,7 @@ Glossary routes.php A file in APP/Config that contains routing configuration. This file is included before each request is processed. - It should connect all the routes your application needs so + It should connect all the routes your application needs so requests can be routed to the correct controller + action. DRY diff --git a/en/cakephp-overview.rst b/en/cakephp-overview.rst index 64eea691d2884368cd5c59f78cd165e188714174..5a3070acb706cc1d64d7d4fc578e9772c09bdcbc 100644 --- a/en/cakephp-overview.rst +++ b/en/cakephp-overview.rst @@ -13,7 +13,7 @@ used in context. .. toctree:: :maxdepth: 1 - + cakephp-overview/what-is-cakephp-why-use-it cakephp-overview/understanding-model-view-controller cakephp-overview/where-to-get-help diff --git a/en/cakephp-overview/understanding-model-view-controller.rst b/en/cakephp-overview/understanding-model-view-controller.rst index e30dbf692dd2bb7b9e0f0841e1ff2f3ec0a7ab29..cf7d26ca1989077dbc98af3e603bb0a2f7136382 100644 --- a/en/cakephp-overview/understanding-model-view-controller.rst +++ b/en/cakephp-overview/understanding-model-view-controller.rst @@ -20,9 +20,9 @@ But in general they stand for the major concepts around which you implement your application. In the case of a social network, the Model layer would take care of -tasks such as saving the user data, saving friends associations, storing -and retrieving user photos, finding new friends for suggestions, etc. -While the model objects can be thought as "Friend", "User", "Comment", or +tasks such as saving the user data, saving friends' associations, storing +and retrieving user photos, finding suggestions for new friends, etc. +The model objects can be thought as "Friend", "User", "Comment", or "Photo". The View Layer @@ -33,25 +33,25 @@ Model objects, it is responsible for using the information it has available to produce any presentational interface your application might need. For example, as the Model layer returns a set of data, the view would use it -to render a HTML page containing it. Or a XML formatted result for others to +to render a HTML page containing it, or a XML formatted result for others to consume. -The View layer is not only limited to HTML or text representation of the data, -it can be used to deliver a wide variety of formats depending on your needs, +The View layer is not only limited to HTML or text representation of the data. +It can be used to deliver a wide variety of formats depending on your needs, such as videos, music, documents and any other format you can think of. The Controller Layer ==================== -The Controller layer handles requests from users. It's responsible for rendering -back a response with the aid of both the Model and the View Layer. +The Controller layer handles requests from users. It is responsible for rendering +a response with the aid of both the Model and the View layer. -Controllers can be seen as managers taking care that all needed resources for +A controller can be seen as a manager that ensures that all resources needed for completing a task are delegated to the correct workers. It waits for petitions from clients, checks their validity according to authentication or authorization rules, -delegates data fetching or processing to the model, and selects the correct -type of presentational data that the client is accepting, to finally delegate -this rendering process to the View layer. +delegates data fetching or processing to the model, selects the +type of presentational data that the clients are accepting, and finally delegates +the rendering process to the View layer. CakePHP Request Cycle @@ -66,12 +66,12 @@ resource in your application. This request is first processed by a dispatcher which will select the correct controller object to handle it. Once the request arrives at the controller, it will communicate with the Model layer -to process any data fetching or saving operation that might be needed. -After this communication is over, the controller will proceed at delegating to the -correct view object the task of generating an output resulting from the data +to process any data-fetching or -saving operation that might be needed. +After this communication is over, the controller will proceed to delegate to the +correct view object the task of generating output resulting from the data provided by the model. -Finally, when this output is generated, it is immediately rendered to the user +Finally, when this output is generated, it is immediately rendered to the user. Almost every request to your application will follow this basic pattern. We'll add some details later on which are specific to diff --git a/en/cakephp-overview/what-is-cakephp-why-use-it.rst b/en/cakephp-overview/what-is-cakephp-why-use-it.rst index 8bc34f8431947c15c41ad75fb6a67cf5c013a6c9..b8ab5b41f2946ff1638352afabc7c0229800f0fa 100644 --- a/en/cakephp-overview/what-is-cakephp-why-use-it.rst +++ b/en/cakephp-overview/what-is-cakephp-why-use-it.rst @@ -36,23 +36,23 @@ Here's a quick list of features you'll enjoy when using CakePHP: for database interaction. - Code generation. - `MVC `_ - architecture. -- Request dispatcher with clean, custom URLs and routes. + architecture +- Request dispatcher with clean, custom URLs and routes - Built-in - `validation `_. + `validation `_ - Fast and flexible `templating `_ - (PHP syntax, with helpers). -- View Helpers for AJAX, JavaScript, HTML Forms and more. -- Email, Cookie, Security, Session, and Request Handling - Components. + (PHP syntax, with helpers) +- View helpers for AJAX, JavaScript, HTML forms and more +- Email, cookie, security, session, and request handling + Components - Flexible - `ACL `_. -- Data Sanitization. -- Flexible `Caching `_. -- Localization. + `ACL `_ +- Data sanitization +- Flexible `caching `_ +- Localization - Works from any web site directory, with little to no - `Apache `_ configuration involved. + `Apache `_ configuration involved .. meta:: diff --git a/en/cakephp-overview/where-to-get-help.rst b/en/cakephp-overview/where-to-get-help.rst index 3e47229dec0932cbeee2ed7547181e917d4eefa4..1bd1bb9163062aae49e99c326020c72a185b07d4 100644 --- a/en/cakephp-overview/where-to-get-help.rst +++ b/en/cakephp-overview/where-to-get-help.rst @@ -35,7 +35,7 @@ with the community and gain instant fame and fortune. The API ======= -`http://api20.cakephp.org/ `_ +`http://api.cakephp.org/ `_ Straight to the point and straight from the core developers, the CakePHP API (Application Programming Interface) is the most @@ -76,27 +76,24 @@ donate your brand new sports car. .. _cakephp-official-communities: -CakePHP Official Communities -============================ -CakePHP also has it's official group in most popular social networking sites like Facebook, Google Plus. There are -thousands of people discussing CakePHP projects, helping each other, solving problems, building projects -and sharing ideas. It can be a great resource for finding archived answers, frequently asked questions, and -getting answers to immediate problems. Join other CakePHP users in the following communities. - -- `CakePHP Google Group `_ -- `CakePHP Facebook Group `_ -- `CakePHP Google Plus Community `_ +Official CakePHP discussion group +================================= +`CakePHP Google Group `_ +CakePHP also has its official discusson group on Google Groups. +There are thousands of people discussing CakePHP projects, helping each other, +solving problems, building projects and sharing ideas. +It can be a great resource for finding archived answers, frequently asked questions, and +getting answers to immediate problems. Join other CakePHP users and start discussing. -CakePHP Questions -================= -`http://ask.cakephp.org/ `_ +Stackoverflow +============= -Simply register/login and ask a question. Wait until you've got some answers -and pick the correct answer. You can view, comment and vote on previously asked -and solved questions as well. +`http://stackoverflow.com/ `_ +Tag your questions with ``cakephp`` and the specific version you are using to enable +existing users of stackoverflow to find your questions. .. meta:: :title lang=en: Where to Get Help diff --git a/en/console-and-shells.rst b/en/console-and-shells.rst index 561a6eb6472b6c1d32dfe3617a3259c4b9b042f7..cdd2ff5022e5a49410960cff18ba6c5e2205ce70 100644 --- a/en/console-and-shells.rst +++ b/en/console-and-shells.rst @@ -681,9 +681,9 @@ make building subcommand parsers easier, as everything is an array:: 'help' => __('Check the permissions between an ACO and ARO.'), 'parser' => array( 'description' => array( - __("Use this command to grant ACL permissions. Once executed, the ARO "), - __("specified (and its children, if any) will have ALLOW access to the"), - __("specified ACO action (and the ACO's children, if any).") + __("Use this command to grant ACL permissions. Once executed, the "), + __("ARO specified (and its children, if any) will have ALLOW access "), + __("to the specified ACO action (and the ACO's children, if any).") ), 'arguments' => array( 'aro' => array('help' => __('ARO to check.'), 'required' => true), @@ -693,19 +693,19 @@ make building subcommand parsers easier, as everything is an array:: ) )); -Inside the parser spec, you can define keys for ``definition``, -``arguments``, ``options``, and ``epilog``. You cannot define -subcommands inside an array style builder. The values for -arguments, and options, should follow the format that -:php:func:`ConsoleOptionParser::addArguments()` and :php:func:`ConsoleOptionParser::addOptions()` -use. You can also use buildFromArray on its own, to build an option parser:: +Inside the parser spec, you can define keys for ``arguments``, ``options``, +``description`` and ``epilog``. You cannot define ``subcommands`` inside an +array style builder. The values for arguments, and options, should follow the +format that :php:func:`ConsoleOptionParser::addArguments()` and +:php:func:`ConsoleOptionParser::addOptions()` use. You can also use +buildFromArray on its own, to build an option parser:: public function getOptionParser() { return ConsoleOptionParser::buildFromArray(array( 'description' => array( - __("Use this command to grant ACL permissions. Once executed, the ARO "), - __("specified (and its children, if any) will have ALLOW access to the"), - __("specified ACO action (and the ACO's children, if any).") + __("Use this command to grant ACL permissions. Once executed, the "), + __("ARO specified (and its children, if any) will have ALLOW access "), + __("to the specified ACO action (and the ACO's children, if any).") ), 'arguments' => array( 'aro' => array('help' => __('ARO to check.'), 'required' => true), @@ -755,7 +755,10 @@ would look like: bake fixture Generate fixtures for use with the test suite. You can use `bake fixture all` to bake all fixtures. - Omitting all arguments and options will enter into an interactive mode. + + Omitting all arguments and options will enter into an interactive + mode. +