Funcionalidad de RST y convenciones de AguaClara
Este archivo explicará cómo utilizar la funcionalidad RST, incluyendo imágenes, tablas, código, ecuaciones y referencias tanto internas como entre documentos. Además, este documento está destinado a definir la convención para este proyecto de libro de texto. Cualquier sintaxis incluida en este documento debe utilizarse al contribuir al proyecto del libro de texto. Si te encuentras con una función para la que no existe una convención, por favor edita este archivo para incluirla aquí.
Cómo usar este archivo:
Abre el código fuente del archivo junto al código renderizado. El código fuente se encuentra haciendo clic en «Ver fuente de la página» en la parte superior de la página. Sigue el código fuente y el código renderizado, usando el código fuente como referencia para la sintaxis correcta.
A menudo verás este formato .. word::. La “palabra” en este caso se llama directiva. Las directivas son lo que usa RST para formatear texto. Las directivas permiten la inclusión de figuras, matemáticas, tablas, referencias, color y mucho más.
También verás a menudo este formato .. _words_separated_by_underscores:. Se llaman etiquetas, y existen para que la ubicación de la etiqueta pueda referenciarse en alguna otra sección o documento del libro de texto. Se definen por .. _ al principio de la etiqueta y : al final de la etiqueta. Hay una convención sobre cómo nombrar etiquetas. Así que antes de empezar a escribir etiquetas a la ligera en tus documentos de libro de texto, lee todo este documento y úsalo como tu biblia de convención. Para etiquetas y todo lo demás.
Importante
La correcta sangría y el espaciado entre líneas son extremadamente importantes al escribir en RST
Encabezados, viñetas y listas numeradas
Encabezados
Los encabezados se definen por un subrayado y a veces por un subrayado que consiste en uno de los siguientes caracteres: *, =, -, ^, and ". RST no proporciona ninguna jerarquía de caracteres particular sobre otro para definir títulos, secciones, subsecciones, etc. El usuario indica la jerarquía de caracteres para los encabezados y puede usar el orden que desee, y el orden puede cambiar entre documentos. Sin embargo, es mejor ceñirse a la misma convención durante todo el proyecto. Esta es la convención para el libro de texto de AguaClara:
* con línea de encima, para los títulos de los documentos
=, para secciones
-, para subsecciones
^, para subsecciones
«, para subsubsecciones
Cada título, sección y subsección debe tener una etiqueta delante. Las etiquetas para los títulos de documentos deben comenzar por title y las etiquetas para encabezados deben comenzar por heading. Por ejemplo, la etiqueta de título de este documento es title_aguaclara_rst_convention y la de este encabezado es heading_headings_bullets_and_lists. Siempre debe haber una línea en blanco entre la etiqueta y el encabezado real, de lo contrario las referencias a la etiqueta no funcionan. Por motivos de legibilidad del documento, incluye 3 líneas en blanco antes de la etiqueta de sección y 2 líneas en blanco antes de la etiqueta de subsección. Los encabezados menores (subsubsecciones y posteriores) no necesitan tener etiquetas, y debe haber una línea en blanco entre los encabezados inferiores y el contenido precedente. Aquí tienes un ejemplo. Observa la cantidad y ubicación de las líneas en blanco:
.. _title_example_document_title:
****************
Document Title
****************
Words go here
.. _heading_example_section:
Section
=========
Words also go here
.. _heading_example_subsection:
Subsection
------------
Here too!
Subsubsection
^^^^^^^^^^^^^^
Even more words
Dos reglas:
Si se usan sublíneas y sobrelíneas, su longitud debe ser idéntica
La longitud del subrayado debe ser al menos tan larga como el propio título.
Listas y viñetas
Esta sección está tomada de esta primera hoja de trucos. El siguiente código:
* This is a bulleted list.
* It has two items, the second
item uses two lines. (note the indentation)
#. This is a numbered list.
#. It has two items.
Dice:
Esta es una lista con viñetas.
Tiene dos elementos, el segundo usa dos líneas. (fíjate en la sangría)
Esta es una lista numerada.
Tiene dos objetos.
Nota
si dos listas están separadas solo por una línea en blanco, entonces las dos listas no se diferencian.
Cifras
Cada figura debe tener una etiqueta, texto alternativo y un pie de foto. Las etiquetas de figuras deben comenzar por figure. A continuación, las dos figuras están etiquetadas como figure_fluffy_cat y figure_mountain. El texto alternativo es una descripción muy breve de la figura. Debajo de todas las especificaciones de la figura se escribe un pie de foto, con una línea en blanco para separar las especificaciones del pie de foto.
Utiliza la siguiente sintaxis para incluir cifras de fuentes en línea:
.. _figure_fluffy_cat:
.. figure:: https://www.catster.com/wp-content/uploads/2017/08/A-fluffy-cat-looking-funny-surprised-or-concerned.jpg
:width: 200px
:align: center
:height: 100px
:alt: external figure
This is a caption.
Utiliza esta sintaxis para las figuras que se encuentran en el repositorio /Textbook en GitHub:
.. _figure_mountain:
.. figure:: ../Images/mountain.jpg
:width: 300px
:align: center
:alt: internal figure
Here is a figure tagged ``figure_mountain``. Specify the figure location with folder/image.jpg.
The base directory for figure location is the directory of the file you are writing.
In this case, that is Textbook/Textbook_Creation_Help.
Figura 267 y Figura 268 son las dos figuras generadas usando el código anterior.
Figura 267 Esto es un pie de foto.
Consulta Figura 268 para una vista típica de la montaña.
Figura 268 Aquí tienes una figura etiquetada figure_mountain. Especifica la ubicación de la figura con carpeta/image.jpg. El directorio base para la ubicación de la figura es el directorio del archivo que estás escribiendo. En este caso, eso es Libro de texto/Textbook_Creation_Help.
Figura 269 El operador de la planta retira las placas sedimentadoras de un clarificador AguaClara.
Matemáticas y ecuaciones
Math is very cool, and works natively in RST using LaTeX math syntax. In-line math can be written with the following syntax: :math:`y = ax^2 + bx + c` which displays \(y = ax^2 + bx + c\). To display equations in their own line, use the following syntax:
.. math::
:label: quadratic_equation
y = ax^2 + bx + c
Que se muestra como:
Las ecuaciones no tienen etiquetas, pueden referenciarse a través de sus etiquetas, como puedes ver arriba. Las etiquetas de ecuaciones no necesitan empezar con una palabra en particular, a diferencia de las etiquetas. No todas las ecuaciones necesitan etiqueta. Solo etiqueta las ecuaciones que necesitas referenciar. Si necesitas referenciar una ecuación que no tiene etiqueta, ponle una intuitiva. Todas las ecuaciones están numeradas, independientemente de si están etiquetadas o no. También se pueden generar ecuaciones complejas, ya que RST utiliza matemáticas LaTeX.
\[n_{\rm{offset}} = \sum_{k=0}^{N-1} \frac{s_k}{n_k} \ln \left( \frac{k}{k!} \right)\]
Al introducir una nueva ecuación, asegúrese de especificar qué significan los parámetros de la ecuación. Una vez introducida la ecuación, sus parámetros no necesitan ser explicados cuando se muestren en el futuro. Utilice la siguiente sintaxis para introducir ecuaciones:
.. math::
:label: continuity_equation_example
\bar v_1 \frac{\pi D_1^2}{4} = \bar v_2 \frac{\pi D_2^2}{4}
| Such that:
| :math:`Q =` fluid flow rate
| :math:`\bar v =` fluid average velocity
| :math:`A =` pipe area
| :math:`r =` pipe radius
| :math:`D =` pipe diameter
Tablas
Las tablas deben hacerse usando csv para ser compatibles con Excel:
.. _table_an_example_table:
.. csv-table:: This table has a title
:header: "name", "firstname", "age"
:widths: 20, 20, 10
:align: center
"Smith", "John", 40
"Smith", "John, Junior", 20
El bloque de código anterior genera la siguiente tabla:
Nombre |
Nombre de pila |
Edad |
|---|---|---|
Smith |
John |
40 |
Smith |
John, Junior |
20 |
Cada tabla debe tener una etiqueta, mostrada en el ejemplo anterior como table_an_example_table. La etiqueta de una tabla debe comenzar por table
Enlaces y referencias
Enlaces
Links are fairly straightforward, use the following syntax, `hyperlink word display <https://www.aguaclarareach.org/>`_, and look like this hyperlink word display. If you will be using the same link many times in a document, you can place this line at the end of the document:
.. _AguaClara: http://aguaclaraReach.org/
Ahora, la AguaClara_ sintáctica enlazará al sitio especificado: AguaClara
Referencias
Las referencias funcionan llamando a cualquier «destino»: ya sea etiquetas (títulos, encabezados, figuras y tablas) o etiquetas (ecuaciones). Estos formatos de referencia funcionan internamente: llamando a algo dentro del mismo documento y externamente, llamando contenido en otro documento dentro de ese mismo proyecto.
Importante
Antes de empezar a etiquetar y etiquetar contenido con cualquier grado de desorden, asegúrate de no estar repitiendo etiquetas o etiquetas. Puedes comprobar si tu etiqueta o etiqueta está tomada visitando bibliotecas en GitHub. Check here for tags and labels:.
Títulos y encabezamientos de documentos
This content should be called with the :ref:`tag` functionality. You can also choose what text will be shown. For example, :ref:`This text <heading_links_and_references>` gives This text.
Figuras y tablas
These can be referenced in the exact same way as titles and headings. However, they can also be referenced using the :numref:`tag` syntax. When this is done, there cannot be text written that will link to the figure. Instead, what shows up is “Fig. 3” or “Table 3”.
Figures:
:numref:`figure_fluffy_cat`gives Figura 267Tables:
:numref:`table_an_example_table`gives Tabla 36
Ecuaciones
Equations are a little different, :ref:`label` does not work. They are instead called with the :eq:`label` syntax. You cannot choose what text displays in the reference like you can with titles, headings, figures, and tables. Whenever you reference an equation, parentheses surrounding the equation’s number will be the linked-text.
Equations:
:eq:`quadratic_equation`only generates a number in parentheses. Thus, this reference is usually preceeded by the word: “equation.” Like this: Equation (408).
Citas
Muy utilizado esta referencia
La referencia entre paréntesis puede producirse en Sphinx usando la extensión sphinxcontrib-bibtex.
La extensión sphinxcontrib-bibtex permite insertar BibTeX citas en la documentación generada por Sphinx.
La prórroga define una nueva directiva bibliography y un nuevo rol cite .
Estos funcionan de forma similar al entorno thebibliography y al comando \cite del LaTeX.
Las referencias se almacenan en un archivo BibTeX de texto plano separado. Actualmente, solo se soportan los estilos BibTeX unsrt y plain .
Además, los PDFs de las fuentes se almacenan en la carpeta «_static/references», que utiliza enlaces internos, asegura que nunca perdamos el acceso y mantiene todo en un solo lugar.
Ejemplo
Dentro del cuerpo del documento, utiliza la siguiente sintaxis:
See :cite:`ex-Strunk1979` for an introduction to stylish blah, blah...
Y coloca la directiva al final del documento:
.. bibliography:: /references.bib
:cited:
:keyprefix: ex-
El «prefijo clave» debe estar relacionado con el tipo de documento. Por ejemplo, cuando se flocculator_design documentos, el prefijo debe ser floc_design- y todas las citas deben estar precedidas con floc_design, y en esta página de ejemplo está «ex». Cada página requerirá su propio prefijo clave, lo que evita confusiones con citas repetidas en Travis.
El archivo references.bib debe contener una bibliografía BibTex, incluyendo una entrada para:
@BOOK{Strunk1979,
title = {The Elements of Style},
publisher = {Macmillan},
year = {1979},
author = {Strunk, Jr., William and E. B. White},
edition = {Third}
}
Un ejemplo práctico: [SW79].
Escribir bloques de código (no código ejecutable real)
You can write code in-line or as a code block. Note that these ways of showing code only display code, they do not generate a code block that actually runs. There are two ways of doing each. For in-line code, use ``this syntax`` or :code:`this syntax`. For code blocks, use this syntax:
.. code::
This is my code block.
O esta sintaxis:
This two colons at the end of this line indicate that the text below, which is separated by a blank line and indented, is a code block::
This is my code block.
Insertando vídeo
Para insertar un vídeo y usarlo como una figura, toma una instantánea instructiva del vídeo. Guárdala como imagen y crea una figura que enlace a esa imagen. Luego, haz que el vídeo se abra cuando se haga clic en él configurando la URL del vídeo como el «destino» de la imagen. Para indicar que es un vídeo, incluye la barra de reproducción. Aquí está el código relevante:
.. figure:: ../Images/Floc_Filter_Floc_Hopper.png
:target: https://www.youtube.com/watch?v=Xp8ygnIOgi0
This is a floc filter forming
Y aquí tienes un ejemplo práctico:
Figura 270 Esto es una formación filtro de flóculos