Repository files navigation

This is the official documentation for the CakePHP project. It is availableonline in HTML, PDF and EPUB formats athttps://book.cakephp.org.

Contributing to the documentation is pretty simple. Please read thedocumentation on contributing to the documentation over onthecookbook forhelp. You can read all the documentation within as it is just in plain textfiles, marked up with ReST text formatting.

There are two ways for building the documentation: with Docker, or by installingthe packages directly on your OS.

Docker will let you create a container with all packages needed to build thedocs. You need to have docker installed, see theofficial docs ofdocker for more information.

Starting in the top-level directory, you can build the providedDockerfileand tag it with the namecakephp/docs by running:

docker build -t cakephp/docs.

This can take a little while, because all packages needs to be downloaded, butyou'll only need to do this once.

Now that the image is built, you can run all the commands to build the docs:

docker run -it --rm -v$(pwd):/data cakephp/docs make html

docker run -it --rm -v$(pwd):/data cakephp/docs make epub

docker run -it --rm -v$(pwd):/data cakephp/docs make latex

docker run -it --rm -v$(pwd):/data cakephp/docs make pdf

All the documentation will output to thebuild directory.

To build the documentation you'll need to install dependencies using:

pip install -r requirements.txt

To run the pip command, python-pip package must be previously installed.

After installing the required packages, you can build the documentation usingmake.

make html

make html-en

make epub

make epub-en

After making changes to the documentation, you can build the HTML version of thedocs by usingmake html again. This will build only the HTML files that havehad changes made to them.

Building the PDF is a non-trivial task.

1. Install LaTeX - This varies by distribution/OS so refer to your packagemanager. You should install the full LaTeX package. The basic one requiresany additional packages to be installed withtlmgr
2. Runmake latex-en.
3. Runmake pdf-en.

At this point the completed PDF should be inbuild/latex/en/CakePHPBook.pdf.

There are currently a number of outstanding issues that need to be addressed.We've tried to flag these with.. todo:: where possible. To see all theoutstanding todo's add the following to yourconfig/all.py

todo_include_todos=True

After rebuilding the HTML content, you should see a list of existing todo itemsat the bottom of the table of contents.

You are also welcome to make and suggestions for new content as commits in aGitHub fork. Please make any totally new sections in a separate branch. Thismakes changes far easier to integrate later on.

Contributing translations requires that you make a new directory using the twoletter name for your language. As content is translated, directories mirroringthe English content should be created with localized content. For more info,please,click here.

• Install elasticsearch. This varies based on your platform, but mostpackage managers have a package for it.
• Clone thedocs_search into aweb accessible directory.
• ModifysearchUrl inthemes/cakephp/static/app.js to point at thebaseurl for your docs_search clone.
• Start elasticsearch with the default configuration.
• Populate the search using tooling found in thecakephp docs builder project.
• You should now be able to search the docs using elasticsearch.