Документация

Внести вклад в документацию просто. Файлы размещаются на https://github.com/cakephp/docs. Не стесняйтесь произвести форк репозитория, добавить своё изменение/улучшение/перевод и возвратить, выдав запрос на pull request (перенос). Вы даже можете редактировать документы в Интернете с помощью GitHub, не загружая файлы – кнопка «Improve this Doc» на любой странице приведёт вас к редактору GitHub для этой страницы.

Документация CakePHP непрерывно интегрируемая, и развёртывается после каждого запроса pull request, на слияние.

Переводы

Отправьте по электронной почте команду docs (docs на cakephp dot org) или перейдите на IRC (#cakephp on freenode), чтобы обсудить любые усилия по переводу если хотите участвовать.

Новый язык перевода

Мы хотим предоставлять переводы, которые максимально полны. Однако в документации могут быть устаревшие переводы, из-за того, что файл перевода давно не обновлялся. Вы всегда должны рассматривать английскую версию - как авторитетную версию.

Если ваш язык не находится в списке текущих языков, свяжитесь с нами через Github, и мы рассмотрим создание для него папки скелета. Следующие разделы являются первыми, которые вы должны рассмотреть, файлы не меняются часто:

  • index.rst
  • intro.rst
  • quickstart.rst
  • installation.rst
  • /intro folder
  • /tutorials-and-examples folder

Напоминание для администраторов документов

Структура всех языковых папок должна отражать состав английской папки. Если структура изменена для английской версии, вы должны применить эти изменения и для других языков.

Например, если в en/file.rst создан новый английский файл, вы должны:

  • Добавить файл и для других языков. : fr/file.rst, zh/file.rst, …

  • Удалить содержимое, но сохраняя информацию title, meta и возможные toc-tree элементы. Следующее примечание будет добавлено, пока никто не перевёл файл:

    File Title
    ##########
    
    .. note::
        The documentation is not currently supported in XX language for this
        page.
    
        Please feel free to send us a pull request on
        `Github <https://github.com/cakephp/docs>`_ or use the **Improve This Doc**
        button to directly propose your changes.
    
        You can refer to the English version in the select top menu to have
        information about this page's topic.
    
    // Если элементы toc-tree находятся в английской версии
    .. toctree::
        :maxdepth: 1
    
        one-toc-file
        other-toc-file
    
    .. meta::
        :title lang=xx: File Title
        :keywords lang=xx: title, description,...
    

Советы переводчикам

  • Выберите ваш язык, на который вы хотите перевести контент, и просмотрите что уже переведено.
  • Не стесняйтесь использовать ваш язык, если он уже существует в книге.
  • Используйте Неофициальные формы.
  • Переведите одновременно и контент и заголовок.
  • По сравнению с английским содержанием, перед отправкой исправления, (если вы что-то исправите, но не интегрируете изменение «вверх по течению» („upstream“) ваше изменение не будет принято).
  • Если вам нужно написать английский термин, оберните его в теги <em>. Например. «asdf asdf Controller asdf» или «asdf asdf Kontroller (Controller) asfd».
  • Не отправляйте частичные(незаконченные) переводы.
  • Не редактируйте раздел ожидающий изменений.
  • Не используйте HTML сущности для акцентирования. В книге используется кодировка UTF-8.
  • Не меняйте разметку (HTML) и не добавляйте новый контент.
  • Если в исходном контенте отсутствует какая-либо информация, отправьте её в первую очередь.

Руководство по форматированию документации

Новая документация CakePHP написана с помощью Текста в формате ReST. ReST (Re Structured Text) - синтаксис простой текстовой разметки, аналогичный markdown (методу уценки), или textile. Для поддержания согласованности рекомендуется, чтобы при добавлении к CakePHP вы следовали этим рекомендациям, о том как форматировать и структурировать свой текст.

Длина строки

Строки текста должны быть обернуты в 80 столбцов (80 символов на строке). Единственным исключение могут быть длинные URL-адреса и фрагменты кода.

Заголовки и разделы

Заголовки разделов создаются путем подчёркивания заголовка символами пунктуации до края текста.

  • # Используется для обозначения названий страниц.
  • = Используется для разделов на странице.
  • - Используется для подразделов.
  • ~ Используется для подсекций.
  • ^ Используется для под-подразделов.

Заголовки не должны вставляться в глубину более 5 уровней. Перед заголовками и после должна идти пустая строка.

Параграфы

Параграфы - это просто блоки текста, причем все линии имеют одинаковые отступы друг от друга. Параграфы должны быть разделены одной пустой строкой.

Встроенная разметка

  • Одна звездочка: текст для выделения (курсивом) Мы используем его для общего выделения/акцента.
    • *текст*.
  • Две звездочки: текст для выделения жирным (полужирный) Мы будем использовать его для имён рабочих каталогов, тем списка, имён таблиц и исключая следующее слово «table».
    • **/config/Migrations**, **articles**, например.
  • Две косых черты(засечки): text для образцов кода. Мы будем использовать его для имён параметров метода, имён столбцов таблицы, имён объектов, за исключением следующего слова «object» и для имён методов/функций – include «()».
    • ``cascadeCallbacks``, ``true``, ``id``, ``PagesController``, ``config()``, etc.

Если в рабочем тексте появляются звездочки или косые чёрточки(засечки), и они могут сломать встроенную разметку, они должны быть экранированы обратной косой чертой.

Встроенная разметка имеет несколько ограничений:

  • Это не может быть вложением.
  • Содержимое не может начинаться или заканчиваться пробелами: * text* это ошибка.
  • Содержимое должно быть отделено от окружающего текста non-word символами. Используйте обратную косую черту, чтобы избежать удаления пробелов: onelong\ *bolded*\ word.

Списки

Разметка списка очень похожа на пометки. Неупорядоченные списки указываются начиная строку с одной звездочки и пробела. Нумерованные списки могут быть созданны с помощью либо цифр, либо # для автоматической нумерации:

* This is a bullet
* So is this. But this line
  has two lines.

1. First line
2. Second line

#. Automatic numbering
#. Will save you some time.

Также можно создавать списки используя отступы, и разделять их пустой строкой:

* First line
* Second line

    * Going deeper
    * Whoah

* Back to the first level.

Списки определений можно сделать так:

term
    definition
CakePHP
    An MVC framework for PHP

Термины не могут быть больше одной строки, но определения могут быть многострочными и все линии должны иметь постоянный отступ.

Ссылки

Существует несколько видов ссылок, и каждый вид имеет своё собственное применение.

Внешние ссылки

Ссылки на внешние документы (ресурсы) могут быть выполнены с помощью следующего:

`External Link to php.net <http://php.net>`_

Полученная ссылка будет выглядеть так: External Link to php.net

Ссылки на другие страницы

:doc:

Разные страницы документации могут быть связаны между собой с использованием роли :doc:. Вы можете ссылаться на указанный документ, используя либо абсолютный, либо относительный путь. Вы должны опустить расширение .rst. Например, если в документе core-helpers/html используется ссылка :doc:`form`, то это значит, что ссылка ссылается на :doc:`/core-helpers`. Если ссылка была такого вида :doc:`/core-helpers`, это значит, что она всегда будет ссылаться на /core-helpers, независимо от того, где она была использована.

Перекрестные ссылки

:ref:

Вы можете перекрёстно ссылаться на любой произвольный заголовок в любом документе, используя :ref: роль. Цели ссылок на метки должны быть уникальными на всём протяжении документации. При создании меток на методы класса, лучше всего использовать class-method в качестве формата вашей метки ссылок.

Наиболее распространенно использование меток над заголовком. Пример:

.. _label-name:

Section heading
---------------

More content here.

В другом месте вы можете ссылаться на вышеуказанный раздел, используя :ref:`label-name`. Текст ссылки будет названием, которому предшествовала ссылка. Вы также можете ввести текст пользовательской ссылки, используя :ref:`Link text <label-name>`.

Предотвращение предупреждений от Sphinx

Sphinx выводит предупреждения, если файл не ссылается в toc-tree. Это отличный способ гарантировать, что все файлы имеют ссылку, направленную на них, но иногда вам не нужно вставлять ссылку на файл, например для ваших epub-contents и pdf-contents файлов. В этих случаях вы можете добавить :orphan: в верхней части файла, чтобы подавить предупреждения о том, что файл не в toc-tree.

Описание классов и их содержания

В документации CakePHP используется phpdomain для предоставления пользовательских директив для описания объектов и конструкций PHP. Использование этих директив и ролей необходимо для правильной индексации и перекрёстных ссылок.

Описание классов и конструкторов

Каждая директива описывает индекс и/или пространство имен.

.. php:global:: name

Эта директива объявляет новую глобальную переменную PHP.

.. php:function:: name(signature)

Определяет новую глобальную функцию вне класса.

.. php:const:: name

Эта директива объявляет новую константу PHP. Вы также можете использовать вложенние внутрь директивы класса, для создания констант класса.

.. php:exception:: name

Эта директива объявляет новое исключение в текущем пространстве имен. Подпись может включать аргументы конструктора.

.. php:class:: name

Описывает класс. Методы, атрибуты и константы, принадлежащие классу, должны находиться внутри тела этой директивы:

.. php:class:: MyClass

    Описание класса

   .. php:method:: method($argument)

    Описание метода

Атрибуты, методы и константы не обязательно должны быть вложенными. Они также могут просто следовать декларации класса:

.. php:class:: MyClass

    Текст о классе

.. php:method:: methodName()

    Текст о методе

См.также

php:method, php:attr, php:const

.. php:method:: name(signature)

Описать метод класса, его аргументы, возвращаемое значение и исключения:

.. php:method:: instanceMethod($one, $two)

    :param string $one: The first parameter.
    :param string $two: The second parameter.
    :returns: An array of stuff.
    :throws: InvalidArgumentException

   This is an instance method.
.. php:staticmethod:: ClassName::methodName(signature)

Опишите статический метод, его аргументы, возвращаемое значение и исключения, см. php:method для использования параметров.

.. php:attr:: name

Описать свойство/атрибут для класса.

Предотвращение предупреждений от Sphinx

Sphinx выводит предупреждения, если функция ссылается на несколько файлов. Это отличный способ гарантировать, что вы не добавляли функцию два раза, но иногда вы действительно хотите написать функцию в двух или более файлах, например. /development/debugging ссылается на /development/debugging и на /core-libraries/global-constants-and-functions. В этом случае вы можете добавить :noindex: под функцией debug для подавления предупреждений. Сохраните хотя бы одну ссылку без :no-index: чтобы сохранить ссылку на функцию:

.. php:function:: debug(mixed $var, boolean $showHtml = null, $showFrom = true)
    :noindex:

Перекрестная ссылка

Следующие роли относятся к объектам PHP, а ссылки генерируются, если найдена соответствующая директива:

:php:func:

Ссылка на функцию PHP.

:php:global:

Ссылка на глобальную переменную, имя которой имеет префикс $.

:php:const:

Укажите глобальную константу или константу класса. Константы класса должны предшествовать имени класса:

DateTime has an :php:const:`DateTime::ATOM` constant.
:php:class:

Ссылка на класс по имени:

:php:class:`ClassName`
:php:meth:

Ссылка на метод класса. Эта роль поддерживает оба вида методов:

:php:meth:`DateTime::setDate`
:php:meth:`Classname::staticMethod`
:php:attr:

Ссылка на свойство объекта:

:php:attr:`ClassName::$propertyName`
:php:exc:

Ссылка на исключение.

Исходный код

Буквенные кодовые блоки создаются путем окончания абзаца на ::. Литерал блока должен быть отступом, и, как и все абзацы, должен разделяться одиночными линиями:

Это абзац::

    while ($i--) {
        doStuff()
    }

Это снова очередной текст.

Буквенный текст не изменяется или не форматируется, за исключением того, что удаляется один уровень отступов.

Примечания и предупреждения

Часто так бывает, что вы хотите сообщить читателю важный совет, специальное примечание или потенциальную опасность. Упоминания в sphinx используются только для этого. Есть пять видов предупреждений.

  • .. tip:: Советы используются для документирования или повторного использования интересной или важной информации. Содержание директивы должно быть написано полностью в одном предложении и включать все соответствующие знаки препинания.
  • .. note:: Примечания используются для документирования особо важной части информации. Содержание директивы должно быть написано полностью в одном предложении и включать все соответствующие знаки препинания.
  • .. warning:: Предупреждения используются для документирования потенциальных камней преткновения или информации, относящейся к безопасности. Содержание директивы должно быть написано в полных предложениях и включать все соответствующие знаки препинания.
  • .. versionadded:: X.Y.Z «Version added» заметки используются для отображения предупреждений специально для новых функций, добавленных в определенной версии, X.Y.Z является версией с который была добавлена эта функция.
  • .. deprecated:: X.Y.Z В отличие от предупреждений «version added», «deprecated» предупреждения используются для уведомления об устаревшей функции, X.Y.Z является версией на которой упомянутый признак устарел.

Все примечания сделаны одинаковыми:

.. note::

    Отступ и предшествует и следует пустая строка. Так же, как для параграфа.

Этот текст не является частью примечания.

Образец

Совет

Это полезный tid-bit, который вы вероятно забыли.

Примечание

Вы должны обратить внимание на это.

Предупреждение

Это может быть опасно.

Добавлено в версии 2.6.3: Эта замечательная функция была добавлена в версию 2.6.3

Не рекомендуется, начиная с версии 2.6.3: Эта старая функция стала устаревшей в версии 2.6.3