Documentación#
Truco
La documentación en este sitio está escrita en ReStructuredText, o RST para abreviar. Revise RST Primer si no está familiarizado con RST.
Esta página le guiará a través de la redacción de una magnífica documentación para el proyecto UBports que pueda ser destacada en este sitio.
Directrices de la documentación#
These rules govern how you should write your documentation to avoid problems with style, format, or linking.
Título#
Todas las páginas deben tener un título del documento que se mostrará en la tabla de contenidos (barra lateral izquierda) y en la parte superior de la página.
Titles should be «sentence cased» rather than «Title Cased». For example:
Incorrect casing:
Writing A Good Bug Report
Correct casing:
Writing a good bug report
Correct casing when proper nouns are involved:
Installing Ubuntu Touch on your phone
No existe una única definición de como usar las mayúsculas que siga todo el mundo, pero aplicarlas en una frase es sencillo. Esto ayuda a mantener las mayúsculas en la tabla de contenidos consistentes.
Los títulos de las páginas están subrayados con signos de igual. Por ejemplo, la anotación para Informando de errores incluye el siguiente título:
Bug reporting
=============
Tenga en cuenta que:
El título se inicia en mayúscula
El título se subraya con signos de igual
El subrayado abarca el título completamente sin sobresalir
Algunos ejemplos incorrectos de títulos:
Mayúsculas incorrectas
Bug Reporting =============
Subrayado demasiado corto
Bug reporting =====
Subrayado demasiado largo
Bug reporting ================
Encabezamientos#
Existen varios niveles de encabezamientos que puede colocar en su página. Se muestran aquí estos niveles en orden:
Page title
==========
Level one
---------
Level two
^^^^^^^^^
Level three
"""""""""""
Cada nivel de encabezamiento crea una sub-sección en el árbol de la tabla de contenido global disponible cuando se crea la documentación. En la versión primaria (web) de la documentación, esto solo muestra cuatro niveles desde el nivel superior de la documentación. Evite utilizar más niveles de títulos de los que se muestran en este árbol, ya que dificulta la navegación de su documento. Si debe usar muchos niveles de encabezamiento, esto es una buena señal de que su documento se debería dividir en varias páginas.
Tabla de contenidos#
La gente no puede navegar a su nueva página si no pueden encontrarla. Tampoco Sphinx. Por eso necesita añadir nuevas páginas a la tabla de contenidos de Sphinx.
Puede hacer esto añadiendo la página al archivo index.rst en el mismo directorio en que la haya creado. Por ejemplo, si ha creado un archivo titulado «newpage.rst», añadiría la línea marcada con un mayor que (>) en el índice mas cercano:
.. toctree::
:maxdepth: 1
:name: example-toc
oldpage
anotheroldpage
> newpage
El orden importa. Si le gustaría que su página aparezca en un sitio determinado de la tabla de contenidos, sitúela allí. En el ejemplo anterior, la nueva página sería añadida al final de esta tabla de contenidos.
Moving pages#
Sometimes it becomes necessary to move a page from one place in the documentation to another. Generally this is to improve document flow: For example, it makes more sense for the page to come after a page you’ve just added in a different section.
However, people link to our documentation from many sources that we do not control. Blogs, websites, and other documentation sites can direct people here using links that they may never update. It is a terrible experience to follow a link from a different site and land on a 404 page, left to your own devices to find your way in restructured documentation.
We use a tool called Rediraffe to avoid this bad experience. Rediraffe creates redirect pages which can send a user from an old, invalid link to a new, useful link. Please create a redirect link when changing a page’s name or moving a page within the documentation’s directory structure. Redirect links are created by placing the filename of the old document and the filename of the new document, relative to the documentation’s root, in the redirects.txt file.
We use Rediraffe’s checkdiff builder to ensure that pages are not deleted from the documentation without a redirect in place. This builder is run as part of the build.sh script in the repository and as part of our automated build once you submit a Pull Request.
What follows are some examples of situations where you should create redirects.
You are moving systemdev/calendars.rst to appdev/calendars.rst. Add the following to the redirects.txt file:
"systemdev/calendars.txt" "appdev/calendars.txt"
You are moving appdev/clickable.rst into several pages in appdev/clickable/ to give significantly more information about the tool than there was previously. You have created an introduction page, appdev/clickable/introduction.rst. In this case, it would be a good idea to redirect the old page to the new introduction page. This can be done by adding the following to redirects.txt:
"appdev/clickable.rst" "appdev/clickable/introduction.rst"
Advertencias#
Sus ediciones no deben introducir ninguna advertencia en la construcción de la documentación. Si ocurre alguna advertencia, la construcción fallará y su solicitud de incorporación de cambios («pull request») será marcada con una «X» roja. Asegúrese de que su RST es válido y correcto antes de crear su solicitud de incorporación de cambios («pull request»). Esto se hace automáticamente (vía sphinx-build fallando con su error) si sigue ref:nuestras instrucciones de construcción <doc-contribution-workflow> siguientes.
Longitud de línea#
No hay restricciones para la longitud de línea en este repositorio. No rompa las líneas en una longitud arbitraria. En su lugar, active el ajuste de línea en su editor de texto.
Flujo del trabajo de contribución#
Los siguientes pasos le ayudarán a hacer una contribución a esta documentación después de que haya escrito un documento.
Nota
Necesitará una cuenta de GitHub para completar estos pasos. Si no tiene una, pulse aquí para comenzar el proceso de hacerse una cuenta.
Bifurcando el repositorio#
Puede realizar ediciones mas avanzadas de nuestra documentación mediante la bifurcación (fork) de ubports/docs.ubports.com en GitHub. Si no está seguro de como hacerlo, revise la excelente guía de GitHub sobre como bifurcar proyectos.
Construyendo la documentación#
Si desea construir esta documentación antes de enviar una solicitud de extracción o PR (que debería), siga estas instrucciones en su copia local de su bifurcación (fork) del repositorio.
La documentación se puede construir ejecutando ./build.sh en la raíz de este repositorio. El guión (script) creará también un entorno de construcción virtual en ~/ubportsdocsenv si no hay ninguno presente.
Si todo fue bien, puede ir al directorio _build/html y abrir index.html para ver la documentación de UBports.
Si tiene algún problema construyendo los documentos, la primera cosa que debe intentar es eliminar el entorno de construcción. Ejecute rm -r ~/ubportsdocsenv e intente la construcción de nuevo. Dependiendo de cuando usó por primera vez el guión (script) de construcción, puede que necesite ejecutar la orden rm con sudo.
Final check of your contribution#
After you have created your PR on github, the CI (continuous integration) system will make a test build of your contribution. Please double check whether this builds successfully and whether the result looks as you intended it to:
Scroll to the bottom of the «Conversation» tab of your PR on github, here you will see the checks (You may have to click on «Show all checks»)
It can have a yellow dot, i.e., «pending» then wait a few more seconds.
Or it may have a red X, i.e., it failed. In this case please check why it failed
If it shows a green check mark, it means the PR could be built successfully
Now please click on «Details»,
then «Artifacts» on the top right,
then «_build/html/..index.html»,
and finally on «Go to start page».
Now you can browse a complete build of the UBports docs site with your contribution included. Double check whether your changes look ok.
Métodos alternativos para contribuir#
Traducciones#
Puede encontrar los componentes de este documento para traducir en its project in UBports Weblate.
Escribir documentos en un formato diferente a RST#
Si le gustaría escribir documentos para UBports pero no está cómodo escribiendo en ReStructuredText, escríbalo sin formato y publíquelo en UBports Forum en la sección relevante (probablemente en General). Alguien le ayudará a revisar su borrador y escribir el necesario ReStructuredText.
Incómodo con Git#
Si ha escrito un documento completo en ReStructuredText pero no está cómodo usando Git o GitHub, publíquelo en UBports Forum en la sección relevante (probablemente en General). Alguien le ayudará a revisar su borrador y enviarlo a esta documentación.
POR HACER actuales#
Esta sección lista los POR HACER que han sido incluidos en esta documentación. Si sabe como arreglar alguno ¡por favor envíenos una solicitud de incorporación de cambios («pull request») para hacerlo mejor!
Para crear un por hacer, añada esta marca a su página:
.. todo::
My todo text
Por hacer
There is also another way to create somewhat more featureful webapps, sometimes referred to as webapp+ or alternative container. This needst to be properly documented. It’s a simple qml app that can be easily configured. Creation is almost as simple as “classic” webapp, but result is more powerfull with the a nice navigation feature. A rather advanced example of this is the YouTube app from Mateo Salta which has quite some modifications on top of the template.
(La entrada original se encuentra en /home/docs/checkouts/readthedocs.org/user_builds/docsubportscom-spanish/checkouts/latest/appdev/webapp/index.rst, línea 19.)
Por hacer
Document the process for Nexus 4 (mako)
(La entrada original se encuentra en /home/docs/checkouts/readthedocs.org/user_builds/docsubportscom-spanish/checkouts/latest/systemdev/kernel-hal.rst, línea 57.)