Primer de Sphinx

Formato básico

• Negrita: **Negrita**

• Cursiva: *Cursiva*

• Monoespacio: ``Monoespacio``

• Listas no ordenadas: Inicia los elementos con - o *.

• Listas ordenadas: Inicia los elementos con números o #.

• Encabezados: Subraya (y opcionalmente sobrescribe) el encabezado con cualquiera de los caracteres #, *, =, -, ^ o �? El nivel del encabezado se deducirá del orden en que se encuentren. Los documentos de Bitxor generalmente usan solo 3 niveles indicados con los caracteres #, * y =.

  ##########
  Título principal
  ##########
  
  Encabezado nivel 2
  **************
  
  Encabezado nivel 3
  ==============
  
  Texto normal.
  

• Bloque citado: Indenta con un espacio. ¡La sangría es fundamental en RST!

• Bloques de código: Consulta la sección de directivas a continuación.

Enlaces

• Enlace externo: Encerrado entre comillas invertidas, seguido de doble guion bajo.

  `Título del enlace <url-del-enlace>`__
  

• Enlace interno a otra página:

  :doc:`Título del enlace <ruta-del-archivo-relativa-sin-extensión>`
  

  La ruta es relativa al archivo actual, o absoluta (desde el directorio “source�? si comienza con /.

  Puedes omitir la parte del Título del enlace y usar el título real del documento (su primer encabezado):

  :doc:`ruta-del-archivo-relativa-sin-extensión`
  

• Enlace interno a una etiqueta (ancla):

  :ref:`Título del enlace <nombre-de-la-etiqueta>`
  

  Y define etiquetas (en cualquier archivo) de la siguiente manera:

  .. _nombre-de-la-etiqueta:
  
  Aquí viene una nueva sección
  ========================
  

  Si la etiqueta aparece justo antes de un encabezado (como en el ejemplo anterior), puedes omitir la parte del “Título del enlace�?en el enlace y se usará el texto del encabezado:

  :ref:`nombre-de-la-etiqueta`
  

Tablas

Existen mecanismos diferentes para representar tablas en Sphinx. El más utilizado en los documentos de Bitxor es el csv-table:

.. csv-table::
   :header: "Encabezado 1", "Encabezado 2", "Encabezado 3"
   :widths: 25 25 50
   :delim: ;

   Datos 1; Datos 2; Datos 3
   Datos 4; Datos 5; Datos 6

:header:, :widths: y :delim: son opcionales y no requieren mucha explicación. :delim: indica el carácter utilizado para separar las columnas en los datos que siguen.

Ten en cuenta que los datos están sangrados para que se alineen con la palabra csv-table (es decir, sangrados por 3 espacios).

Agregar páginas

En los documentos de Bitxor, todas las páginas aparecen en la barra de navegación izquierda, por lo tanto, todas las páginas deben aparecer en un árbol TOC. Cualquier página puede indicar qué otras páginas son sus hijos utilizando la directiva toctree (puedes buscar ejemplos en los documentos actuales).

Si agregas una nueva página, además de crear el archivo .rst en la carpeta adecuada, deberás agregar su nombre al toctree de su página principal:

.. toctree::
    :maxdepth: 1

    doc-repos
    doc-workflow
    doc-sphinx-primer
    doc-common-tasks

:maxdepth: 1 indica que no deseas que se enumeren las secciones de la página ni sus subpáginas. Si la página tiene subpáginas, le darás su propio toctree para que se muestren.

Puedes agregar :hidden: para que la lista de páginas no se muestre en la página. Aun así, aparecerá en la barra de navegación.

Sustituciones

Sphinx permite definir algunas palabras de código para que sean sustituidas por un texto más largo. Las palabras de código se indican entre caracteres de barra vertical |así| y pueden definirse en cualquier lugar. En los documentos de Bitxor, se definen principalmente en el archivo conf.py (en la variable rst_prolog).

La sustitución más utilizada es |nombre-de-codigo|, que se expande a �?a href="#id1">|nombre-de-codigo|�? Existe un problema abierto para eliminar esta en particular.

Directivas útiles

Las directivas tienen la forma .. nombre-directiva:: y son un mecanismo para extender la funcionalidad RST. Sphinx agregó sus propias directivas sobre RST, y los documentos de Bitxor agregaron algunas más (mire la carpeta /source/_ext. Están escritas en Python).

Las directivas pueden tener un parámetro sin nombre después del nombre de la directiva (vea code-block a continuación), o varios parámetros con nombre entre dos puntos : en las líneas a continuación (como ha visto arriba en las Tablas sección).

La directiva cuerpo está separada de la directiva y los parámetros por una línea en blanco y tiene una sangría de 3 espacios.

Estas son las directivas más utilizadas en los documentos de Bitxor (además de las ya mencionadas):

• code-block: Para insertar código resaltado por sintaxis.

  .. code-block:: language
  
     code
  

• figure: Para insertar una imagen subtitulada.

  .. figure:: image-file-path
  
     Caption text.
  

• note, caution, topic: Para insertar un cuadro de color con título (las notas son azules, las precauciones son naranjas). Los temas permiten definir su propio título, de lo contrario será “Nota�?o “Precaución�?

  .. note:: Some text
  
     Some more text.
  

• raw: Para insertar HTML sin formato. Usar solo en caso de emergencia.

  .. raw:: html
  
     HTML code.
  

• tabs: Definir contenido tabulado.

  .. tabs::
  
     .. tab:: Tab1 title
  
        Tab1 content
  
     .. tab:: Tab2 title
  
        Tab2 content
  

• example-code: Código fuente tabulado, con resaltado de sintaxis y enlace al archivo fuente original.

  .. example-code::
  
     .. viewsource:: ../resources/examples/typescript/transfer/DefiningMaxFee.ts
         :language: typescript
         :start-after: /* start block 01 */
         :end-before: /* end block 01 */
  
     .. viewsource:: ../resources/examples/typescript/transfer/DefiningMaxFee.js
         :language: javascript
         :start-after: /* start block 01 */
         :end-before: /* end block 01 */
  

• serializationref: Inserts nicely-formatted serialization documentation.

  .. serializationref:: StructureName