Contribuyendo a fortran-lang.org#

¡Fortran-lang.org es de código abierto y las contribuciones son bienvenidas!

  • Veapaquetes para saber como agregar una entrada al Índice de paquetes

  • Vea mini librospara saber como escribir y estructurar un mini tutorial para la sección Aprender

Introducción#

¿Cómo está escrito el sitio web?

El contenido del sitio web está escrito principalmente como una combinación de Markdown (extensión Myst), HTML y YAML (para datos). Esta fuente es compilada para producir HTML puro que usted verá en el sitio web final.

El sitio web es estático lo que significa que una vez creado, el contenido del sitio es el mismo para todos los usuarios; esto contrasta con muchos sitios web que son dinámicos, lo que significa que pueden ofrecer contenido diferente según el usuario y las entradas proporcionadas por el usuario.

Los componentes estructurales del sitio web están escritos en el generador de sitios Sphinx Static para características estáticas y JavaScript para características dinámicas.

¿Necesito saber HTML para contribuir?

La mayoria del contenido del sitio web está escrito en Markdown, un lenguaje de marcado simple para dar formato al texto. No se preocupe si no lo ha usado antes, ¡es muy fácil de entender!

¿Cómo está construido el sitio web?

El sitio web Fortran-lang utiliza el generador de sitios estáticos Sphinx, basado en Python, para compilar los archivos RST, Markdown y HTML. Se recomienda que los colaboradores instalen Python en su computadora de desarrollo para que los cambios puedan ser previsualizados localmente; sin embargo, esto no es obligatorio ya que las vistas previas del sitio pueden ser generadas durante el proceso de pull request (consulte más abajo para más información). Consulte README.md para saber cómo configurar Sphinx y compilar el sitio web.

La rama predeterminada en el repositorio de Github solo contiene el “código fuente” del sitio web, no el resultado final compilado; un servicio automático compila este código fuente cada vez que se envía una actualización y almacena el resultado compilado en la rama gh-pagesque está disponible en https://fortran-lang.org.

Por lo tanto, como colaborador, solo necesita cargar los cambios en el código fuente del sitio y no el resultado compilado, ya que esto se crea automáticamente a partir del código fuente en la rama predeterminada.

Flujo de trabajo#

Las contribuciones al sitio web son realizadas mediante solicitudes de integración al repositório de github: https://github.com/fortran-lang/webpage/.

El flujo de trabajo para ello es el siguiente:

  1. Cree/actualice una bifurcación (fork) personal de la página web

  2. Cree una rama nueva en su fork

    • El nombre de la rama debe describir concisamente su contribución, por ejemplo, fix-spelling-homepage, update-compiler-info

  3. Realice los cambios en su rama local

  4. Envie su rama modificada a su bifurcación

    • e.g. git push --set-upstream origin fix-spelling-homepage

  5. Cree una solicitud de integración la página web fortran-lang desde su bifurcación modificada

Note: Before opening a pull request you must build your changes locally using Sphinx (see README.md) to verify that your changes build correctly and render as you expect.

Nota: Usted puede continuar enviando cambios a la rama de su bifurcación después de abrir una solicutd de integración - la solicitud de integración será actualizada

Su solicitud de integración será revisada por otros miembros de la comunidad, que podran requerir cambios. Github brinda una interfaz facil en su página web para aplicar (o rechazar) culaquier cambio sugerido por los revisores con un clic . Esto evita tener que copiar manualmente las sugerencias a su copia local y volver a enviarlas. Si usa el botón «Confirmar sugerencia», deberá actualizar la copia local en su computadora usando git pull si tiene la intención de enviar más ediciones desde su computadora.

Una vez que su solicitud de integración sea aprobada, generalmente por al menos otros dos miembros de la comunidad, los encargados la fusionarán en la rama predeterminada de la página web, momento en el cual se publicará en el sitio fortran-lang.org.

Si es necesario, los encargados del repositorio pueden crear una vista previa pública de los cambios propuestos que estarán disponibles para ver en fortran-lang.org/pr/<pr_id>/ donde <pr_id> es el identificador numérico de su solicitud de integración .

Esto permite a los revisores ver directamente el resultado generado de su solicitud de integracion.

Nota: si realizas commits adicionales en la rama de tu pull request, debes recompilar la previsualización del pull request comentando en el pull request con “#build_preview”.

Luego de que el pull request haya sido fusionado y renderizado con éxito, los workflows borrarán la compilación de previsualización.

Nota: si el enlace de vista previa de la solicitud de integración no funciona o no se actualiza después de la reconstrucción, intente agregar un parámetro aleatorio al final de la URL, p. ej. https://fortran- lang.org/pr/98?v=2: el nombre y el valor del parámetro no importan, pero use valores diferentes para cada actualización. Esto obligará a la red de entrega de contenido de GitHub a brindarle una versión actualizada en lugar de una versión almacenada que está desactualizada.

Guía de estilo#

Markdown#

  • Coloque fragmentos de código en bloques de código, señalados con marcas de verificación (``` ). Use el estilo de código en línea (`code`) para extractos de código en línea, palabras clave de lenguaje de programación, nombres de variables y nombres de archivos.

  • Have no more than one sentence per source-code line, and break-up long sentences across multiples lines - this is important to avoid large git diffs and code review blocks on github.

Paquetes de íconos#

Los íconos son una manera fácil de mejorar la estética de la página al dividir pasajes de texto monótonos y llamar la atención sobre los encabezados o la información clave.

Hay tres paquetes de íconos disponibles para usar en fortran-lang.org:

Ejemplo: Tipo de letra awesome

<i class="fas fa-info-circle"></i>

Example: Sphinx design Myst directives

{octicon}`book;1em;sd-text-info`

Visite los sitios web respectivos para explorar los íconos disponibles.

Contenido de la página#

A veces es útil mostrar contenidos de páginas con hipervínculos para páginas extensas. El árbol TOC de la página se ha automatizado y generará el TOC de la página actual. Mientras que el método para generar TOC de todo el directorio en Fortran-lang.org es:

Para páginas en MD:

add the toc tree directive in md at the end of the index page of the directory with the names of the all files in that directory.

````{toctree}  
:hidden:
ARRAY_index 
````

Tutoriales#

Directrices para el contenido de los minilibros.

General#

Utilice el diseño libro.

Siga las directrices de Markdown.

Estilo de código#

Use dos espacios para la tabulación, tabulando los cuerpos de las unidades pero manteniendo la declaración contiene al mismo nivel que su módulo o tipo. Intente limitar la longitud de la línea a 90 caracteres. Estas consideraciones deberían hacer que el código sea más legible y fácil de ver en dispositivos con anchos de ventana de visualización más pequeños.

module m
  implicit none
  private
  public :: a_t

  type :: a_t
    integer :: val
  contains
    procedure :: func
  end type a_t

contains

  subroutine func(self)
    class(a_t), intent(in) :: self
    if (self%val > 0) then
      print *, self%val
    end if
  end function func

end module m

Cada bloque de código debe tener un nivel de tabulación base de 0, incluso si tuviera tabulación si se colocara en un contexto más amplio.

integer :: i1  ! yes
  integer :: i2  ! no

Evite alinear verticalmente :: y los comentarios en línea, ya que esto agrega una carga de mantenimiento y aumenta la longitud de la línea en la mayoría de los casos.

Si un bloque de código contiene líneas que no son Fortran válidas, déjelo como un bloque de código sin idioma para evitar los cuadros rojos del resaltador de sintaxis.

module <module name>
...
end module <module name>

Siéntase libre de omitir el espacio en las expresiones donde ayude con la legibilidad, pero generalmente incluya espacios en blanco alrededor de los operadores.

y1 = a * b
y2 = a*b + c*d  ! instead of a * b + c * d
y3 = a**2 + 1
y4 = (a*b + c*d) / 2
s3 = s1 // s2

Por lo general, agregue un espacio después de las comas, excepto cuando se indexe con valores de índice cortos o nombres de variables.

a(:,1)
a2(1:10, 2:5)
b(i,j)
b2(long_i_name, long_j_name)
b3(i + 2, j)
call some_subroutine(a, b, an_option=.false.)
c = [1, 2, 3, 10]
d = [(i, i = 1, 10)]
do i = 1, 10
! ...

Otras situaciones además de indexaciones simples donde se pueden omitir los espacios en blanco:

  • Aliasing in imports

    use, intrinsic :: iso_c_binding, only: sp=>c_float, dp=>c_double

  • concatenación de cadenas

    print *, 'hello '//'world'

  • Acceso a componentes (atributos) de tipos derivados

    p%x
p%calc_something(a, b)

  • Alrededor de = al pasar argumentos de palabras clave

    call sr(a, b, c=3)
point = t_point(x=1., y=2.)
character(len=:), allocatable :: s

Escriba en mayúscula la primera letra para los comentarios en línea, excepto para los comentarios en línea finales que solo constan de una palabra o una frase corta.

! Compute new values
y = m*x + b  ! meters

Estas recomendaciones de estilo de código son similares a las de la guía de estilo DFTB+.

Texto#

Use sentence case (as opposed to title case) for page and section titles.

Use emphasis (*emphasis*/_emphasis_, rendered as italic) for key words/phrases when they are first introduced, for emphasis, …

Avoid use of strong (**strong**, rendered as bold) within paragraphs, since bold style is used for headings, drawing attention to examples (Example:), admonition/aside titles, etc.

Make use of the admonition/aside (note, tip, important) where appropriate.

  • para agregar una nota al documento md use:

::::{note}
extra information, something that might appear in a footnote
:::::

  • para adicionar una sugerencia al uso del documento md:

::::{tip}
information about best practices, practical tips
:::::

  • para adicionar un texto importante al documento md use:

::::{importrant}
warnings, things to avoid, etc.
:::::

Prefiera incluir la coma Oxford. Por lo general, deja las cosas más claras.

Fortran es rápido, divertido y famoso.