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

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

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

Если ваш язык не находится в списке текущих языков, свяжитесь с нами через 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) и не добавляйте новый контент.

• Если в исходном контенте отсутствует какая-либо информация, отправьте её в первую очередь.

Длина строки¶

Строки текста должны быть обернуты в 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 <https://php.net>`_

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

В документации 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¶

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

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

Исходный код¶

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

Это абзац::

    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::

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

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