Contribuindo na fortran-lang.org#

Fortran-lang.org possui código-fonte aberto e contribuições são bem-vindas!

Introdução#

Como o site é escrito?

O conteúdo do site é primariamente escrito com uma combinação de Markdown (dialeto Myst), HTML and YAML (para dados). Este código-fonte é compilado para produzir HTML puro que no final é o que você vê aqui.

O site é estático que significa que uma vez compilado, o conteúdo do site é o mesmo para todos os usuários; diferentemente de muitos outros sites que são dinâmicos, que podem mostrar um conteúdo diferente dependendo do usuário e das informações fornecidas pelo mesmo.

Componentes estruturais do site são escritos utilizando o gerador de sites Sphinx e JavaScript para os recursos dinâmicos.

Preciso saber HTML para ajudar?

A maior parte do conteúdo do site é escrita em Markdown, uma linguagem simples de marcação para a formatação de texto - mas não se preocupe se você nunca usou Markdown antes, pois é bem fácil de começar a usar!

Como o site é compilado?

O site fortran-lang usa o gerador de sites estáticos feito em Python, Sphinx para compilar RST, Markdown e HTML. É recomendado que colaboradores instalem o Python no seu computador de desenvolvimento, de modo que as mudanças possam ser visualizadas previamente, no entanto, isso não é obrigatório, uma vez que pré-visualizações podem ser geradas durante o processo de PR (veja abaixo para mais informações). Veja o README.md para entender como configurar o Sphinx e gerar o site.

O ramo principal do repositório do GitHub deve apenas conter o código-fonte do site, não arquivos gerados; um serviço automático já gera o site a partir do código-fonte sempre que uma atualização é feita e armazena o resultado no ramo gh-pages que então é mostrado em https://fortran-lang.org.

Deste modo, como colaborador, você apenas precisa fazer o upload de mudanças no código-fonte do site em si e não em seus arquivos gerados, já que este é compilado automaticamente a partir do código-fonte no ramo principal.

Fluxo de Trabalho#

Contribuições ao site são feitas a partir de PR no repositório no github: fortran-lang/webpage.

O fluxo de trabalho segue a forma abaixo:

  1. Criar/Atualizar um fork pessoal da página

  2. Crie um ramo novo no seu fork

    • O nome do ramo deve descrever de forma breve sua contribuição, Ex: fix-spelling-homepage (corrige gramática da página inicial), update-compiler-info (atualiza informações do compilador)

  3. Faça suas mudanças em um ramo local

  4. Mande seu ramo modificado para o seu fork

    • Ex: git push --set-upstream origin fix-spelling-homepage

  5. Crie um PR no repositório fortran-lang/webpage a partir do ramo modificado

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: Você pode continuar a mandar mudanças para o ramo do seu fork após aberto o PR - este será atualizado de acordo com elas

Sei PR será analisado por outros membros da comunidade que pode pedir algumas alterações. O GitHub fornece uma interface amigável em seu site para aplicar (ou rejeitar) qualquer sugestão com um clique de botão. O que evita ter que copiar sugestões manualmente para sua cópia local e por fim enviá-las para o seu PR. Se você usar a opção «Commit suggestion» será necessário atualizar sua cópia local usando git pull caso queira editar mais coisas direto do seu computador.

Uma vez que o PR é aprovado, geralmente por pelo menos dois outros membros da comunidade, ele será enviado para o ramo principal do site pelos mantenedores, que em algum ponto será publicado no site fortran-lang.org.

Se for preciso, os mantenedores do repositório podem compilar uma pré-visualização pública de suas mudanças, que poderá ser visualizada em fortran-lang.org/pr/<pr_id>/ onde <pr_id> é o número identificador do seu PR.

Isso permite que revisores possam ver diretamente o resultado gerado por seu PR.

Note: se você mandar commits subsequentes ao ramo do seu PR, você deve recompilar a pré-visualização comentando no PR “#build_preview”.

Após que seu PR tenha sido aceito e renderizado corretamente, os mantenedores vão deletar a pré-visualização.

Note: se o link para a pré-visualização do seu PR não funcionar ou não atualizar após a recompilação, tente adicionar um parâmetro aleatório ao final da URL, Ex: https://fortran-lang.org/pr/98?v=2 - o nome e o valor do parâmetro não importa, porém use valores diferentes a cada atualização. Isso forçará o GitHub a te entregar a versão atualizada em vez da versão desatualizada que se encontra em cache.

Guia de estilos#

Markdown#

  • Coloque trechos de código em blocos de código, denotado por (```). Use o estilo de código inline (`code`) para trechos de código ao longo do texto, palavras-chave da linguagem de programação, nomes de variáveis e nomes de ficheiros.

  • Não deve ter mais do que uma frase por linha do código-fonte, e deve quebrar frases longas através de múltiplas linhas - isto é importante para evitar grandes diffs no git e blocos de revisão de código no GitHub.

Pacote de icones#

Icones são uma forma fácil de melhorar a estética da página quebrando a monotonia de algumas partes do texto e chamando a atenção para títulos ou informações importantes.

Três pacotes de ícone estão disponíveis para o uso no fortran-lang.org:

Exemplo: Font awesome

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

Exemplo: Sphinx design e diretivas Myst

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

Visite os respectivos sites para navegar pelos ícones disponíveis.

Conteúdo da página#

Às vezes, é útil exibir o conteúdo da página com hiperlink para páginas longas. O sumário da página atual é gerado automaticamente. Já o método para gerar um sumário de todo o diretório em Fortran-lang.org é:

Para páginas em MD:

adicione a diretiva toctree em markdown ao final da página index do diretório contendo o nome de todos os ficheiros naquele diretório.

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

Tutoriais#

Diretrizes para o conteúdo dos mini-books.

Geral#

Use o layout book.

Siga as diretrizes para o Markdown.

Estilo de código#

Use dois espaços para indentação, indente o corpo das unidades de código mas mantenha o comando contains no mesmo nível do seu module ou type. Tente limitar o tamanho da linha em 90 caracteres. Estas ponderações devem tornar o código mais legível em dispositivos com largura de tela menor.

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 bloco de código deve ter o nível indentação base nulo, mesmo em casos em que este seria indentado se colocado em um contexto maior.

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

Evite alinhar verticalmente :: e comentários na mesma linha já que isso adiciona um custo de manutenção e aumenta o tamanho da linha na maioria dos casos.

Se um bloco de código contém linhas que não são códigos válidos em Fortran, deixe-o como um bloco de código sem formatação para evitar erros de sintaxe.

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

Sinta-se livre para omitir o espaçamento nas expressões onde isso ajuda a legibilidade, mas em geral inclua espaços ao redor de 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

Em geral, adicione espaços depois de vírgulas, exceto ao indexar com valores ou nomes de variáveis curtos.

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
! ...

Outras situações em que os espaços podem ser omitidos:

  • Renomear variáveis ao usar módulos

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

  • Concatenação de cadeias

    print *, 'hello '//'world'

  • Acessando componentes (atributos) de tipos derivados

    p%x
p%calc_something(a, b)

  • Ao redor de = ao passar argumentos pelo nome

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

Use a primeira letra maiúscula em comentário na mesma linha, exceto em comentários ao final da linha que consistem apenas em uma palavra ou frase curta.

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

Estas recomendações de estilo são similares as encontradas no guia de estilo do DFTB+.

Texto#

Use maiúsculas apenas no inicio da frase, e não cada palavra, para títulos de páginas e seções.

Use ênfase (*ênfase*/_ênfase_, apresentado em itálico) para palavras-chave/frases quando são introduzidas pela primeira vez, para ênfase, …

Evite o uso de negrito (**negrito**, que será mostrado em negrito) dentro de parágrafos, já que este estilo é usado em títulos ou para chamar atenção a exemplos (Example:), advertência/títulos à parte e etc.

Usar as caixas de diálogo destacado (nota, dica, importante) sempre que apropriado.

  • para adicionar uma nota a um documento em Markdown, use:

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

  • para adicionar uma dica a um documento em Markdown, use:

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

  • para adicionar uma caixa de importante a um documento em Markdown, use:

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

(sugestão para textos em língua inglesa) Inclua a vírgula de Oxford. Geralmente torna as sentenças mais claras.

Fortran é rápido, divertido e célebre.