Documentación¶

Nueva traducción¶

Nos gustaría poder disponer de traducciones que estén todo lo completas posible. Sin embargo hay ocasiones donde un archivo de traducción no está al día, por lo que debes considerar siempre la versión en inglés como la versión acreditada.

Si tu idioma no está entre los disponibles, por favor, contacta con nosotros a través de Github y estudiaremos la posibilidad de crear la estructura de archivos para ello.

Las siguientes secciones son las primeras que deberías considerar traducir ya que estos archivos no cambian a menudo:

• index.rst

• intro.rst

• quickstart.rst

• installation.rst

• /intro (carpeta)

• /tutorials-and-examples (carpeta)

Recordatorio para administradores de documentación¶

La estructura de archivos de todos los idiomas deben seguir la estructura de la versión en inglés. Si la estructura cambia en esta versión debemos realizar dichos cambios en los demás idiomas.

Por ejemplo, si se crea un nuevo archivo en inglés en en/file.rst tendremos que:

• Añadir el archivo en todos los idiomas: fr/file.rst, zh/file.rst,…

• Borrar el contenido pero manteniendo el title, meta información y toc-tree que pueda haber. Se añadirá la siguiente nota mientras nadie traduzca el archivo:

  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.
  
  // If toc-tree elements are in the English version
  .. toctree::
      :maxdepth: 1
  
      one-toc-file
      other-toc-file
  
  .. meta::
      :title lang=xx: File Title
      :keywords lang=xx: title, description,...
  

Consejos para traductores¶

• Navega y edita en el idioma al que quieras traducir el contenido - de otra manera no verás lo que ya está traducido.

• Siéntete libre de bucear en la traducción si ya existe en tu idioma.

• Usa la Forma informal.

• Traduce el título y el contenido a la vez.

• Compara con la versión en inglés antes de subir una corrección (si corriges algo pero no indicas una referencia tu subida no será aceptada).

• Si necesitas escribir un término en inglés envuélvelo en etiquetas <em>. E.g. «asdf asdf Controller asdf» o «asdf asdf Kontroller (Controller) asfd» como proceda.

• No subas traducciones parciales.

• No edites una sección con cambios pendientes.

• No uses entidades HTML para caracteres acentudados, la documentación utiliza UTF-8.

• No cambies significatibamente el etiquetado (HTML) o añadas nuevo contenido.

• Si falta información en el contenido original sube primero una corrección de ello.

Tamaño de línea¶

Las líneas de texto deberían medir como máximo 40 caracteres. Las únicas excepciones son URLs largas y fragmentos de código.

Cabeceras y secciones¶

Las cabeceras de las secciones se crean subrayando el título con caracteres de puntuación. El subrayado deberá ser por lo menos tan largo como el texto.

• # Se utiliza para indicar los títulos de páginas.

• = Se utiliza para los títulos de las secciones de una página.

• - Se utiliza para los títulos de subsecciones.

• ~ Se utiliza para los títulos de sub-subsecciones.

• ^ Se utiliza para los títulos de sub-sub-subsecciones.

Los encabezados no deben anidarse con más de 5 niveles de profundidad y deben estar precedidos y seguidos por una línea en blanco.

Párrafos¶

Párrafos son simplemente bloques de texto con todas las líneas al mismo nivel de indexación. Los párrafos deben separarse por al menos una línea vacía.

Marcado en línea¶

• Un asterisco: texto en cursiva. Lo usaremos para enfatizar/destacar de forma general.

  • *texto*.

• Dos astericos: texto en negrita. Lo usaremos para indicar directorios de trabajo, títulos de listas y nombres de tablas (excluyendo la palabra table).

  • **/config/Migrations**, **articulos**, etc.

• Dos acentos graves (``): texto para ejemplos de código. Lo usaramos para nombres de opciones de métodos, columnas de tablas, objetos (excluyendo la palabra «objeto») y para nombres de métodos y funciones (incluídos los paréntesis )

  • ``cascadeCallbacks``, ``true``, ``id``, ``PagesController``, ``config()``, etc.

Si aparecen asteriscos o acentos graves en el texto y pueden ser confundidos con los delimitadores de marcado habrá que escaparlos con \.

Los marcadores en línea tienen algunas restricciones:

• No pueden estar anidados.

• El contenido no puede empezar o acabar con espacios en blanco: * texto* está mal.

• El contenido debe separarse del resto del texto por caracteres que no sean palabras. Utiliza \ para escapar un espacio y solucionarlo: onelong\ *bolded*\ word.

Listas¶

El etiquetado de listas es muy parecido a Markdown. Las listas no ordenadas se indican empezando una línea con un asterisco y un espacio.

Las listas enumeradas pueden crearse con enumeraciones o # para auto enumeración:

• Esto es una viñeta

  • Esto también, pero esta línea tiene dos líneas.

1. Primera línea

   2. Segunda línea

2. La enumeración automática

3. Te ahorrará algo de tiempo.

También se pueden crear listas anidadas tabulando secciones y separándolas con una línea en blanco:

* Primera línea
* Segunda línea

    * Bajando un nivel
    * Yeah!

* Volviendo al primer nivel

Pueden crearse listas de definiciones haciendo lo siguiente:

Término
    Definición
CakePHP
    Un framework MVC para PHP

Los términos no pueden ocupar más de una línea pero las definiciones pueden ocupar más líneas mientras se aniden consistentemente.

Enlaces¶

Hay diferentes tipos de enlaces, cada uno con sus características.

`Enlace externo a php.net <http://php.net>`_

Describir clases y sus contenidos¶

La documentación de CakePHP usa el phpdomain para proveer directivas personalizadas para describir objetos PHP y constructores. El uso de estas directivas y funciones es necesario para una correcta indexación y uso de las herramientas de referenciación cruzada.

Describir clases y constructores¶

Cada directiva introduce el contenido del índice y/o índice del namespace.

.. php:global:: nombre¶

Esta directiva declara una nueva variable PHP global.

.. php:function:: nombre(firma)¶

Define una nueva función global fuera de una clase.

.. php:const:: nombre¶

Esta directiva declara una nueva constante PHP, puedes usarla también anidada dentro de una directiva de clase para crear constantes de clase.

.. php:exception:: nombre¶

Esta directiva declara una nueva excepción en el namespace actual. La firma puede incluir argumentos de constructor.

.. php:class:: nombre¶

Describe una clase. Métodos, atributos y atributos que pertenezcan a la clase deberán ir dentro del cuerpo de la directiva:

.. php:class:: MyClass

    Descripción de la clase

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

   Descripción del método

Atributos, métodos y constantes no necesitan estar anidados, pueden seguir la siguiente declaración de clase:

.. php:class:: MyClass

    Texto sobre la clase

.. php:method:: methodName()

    Texto sobre el método

.. php:method:: nombre(firma)¶

Describe un método de clase, sus argumentos, salida y excepciones:

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

    :param string $one: El primer parámetro.
    :param string $two: El segundo parámetro.
    :returns: Un array de cosas
    :throws: InvalidArgumentException

   Esto es una instancia de método.

.. php:staticmethod:: ClassName::nombreMetodo(firma)¶

Describe un método estático, sus argumentos, salida y excepciones, ver php:method para opciones.

.. php:attr:: nombre¶

Describe una propiedad/atributo en una clase.

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

Código fuente¶

Los bloques de citas de código fuente se crean finalizando un párrafo con ::. El bloque debe ir anidado y, como todos los párrafos, separados por líneas en blanco:

Esto es un párrafo::

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

Esto es otra vez texto normal.

Los textos citados no son modificados ni formateados salvo el primer nivel de anidamiento, que es eliminado.

Notas y avisos¶

Hay muchas ocasiones en las que quieres avisar al lector de un consejo importante, una nota especial o un peligro potencial. Las admonestaciones en Sphinx se utilizan justo para eso. Hay cinco tipos de admonestaciones:

• .. tip:: Los consejos (tips) se utilizan para documentar o reiterar información interesante o importante. El contenido de la directiva debe escribirse en sentencias completas e incluir todas las puntuaciones apropiadas.

• .. note:: Las notas (notes) se utilizan para documentar una pieza de información importante. El contenido de la directiva debe escribirse en sentencias completas e incluir todas las puntuaciones apropiadas.

• .. warning:: Avisos (warnings) se utilizan para documentar posibles obstáculos o información relativa a seguridad. El contenido de la directiva debe escribirse en sentencias completas e incluir todas las puntuaciones apropiadas.

• .. versionadded:: X.Y.Z las admonestaciones «Version added» se utilizan para mostrar notas específicas a nuevas funcionalidades añadidas en una versión específica, siendo X.Y.Z la versión en la que se añadieron.

• .. deprecated:: X.Y.Z es lo opuesto a versionadded, se utiliza para avisar de una funcionalidad obsoleta, siendo X.Y.Z la versión en la que pasó a ser obsoleta.

Todas las admonestaciones se escriben igual:

.. note::

    Anidado y precedido por una línea en blanco.
    Igual que un párafo.

Este texto no es parte de la nota.