参与 fortran-lang.org 贡献#

Fortran-lang.org 是开源的，欢迎参与进来！

入门#

网站内容是如何编写的？

该网站的内容主要是用 Markdown（Myst 风格）、HTML 和 YAML（用于数据）的组合编写的。 该源代码经过编译以生成纯 HTML，这就是你在最终网站上看到的内容。

这个网站是_静态_的，这意味着一旦建立，网站上的内容对所有用户都是一样的；而许多_动态_网站与之不同，它们可以根据用户和用户提供的输入提供不同的内容。

网站的结构组件是用 Sphinx 静态网站生成器编写的，而 JavaScript 则用于动态特性。

我是否需要了解 HTML 才能做出贡献？

网站的大部分内容都是用 Markdown 编写的，这是一种用于格式化文本的简单标记语言 —— 即使你没用过，也很容易上手！

网站是如何构建的？

Fortran-lang 站点使用基于 Python 的 Sphinx 静态站点生成器 来编译 RST、Markdown 和 HTML 文件。建议贡献者在你用于代码开发的计算机上安装 Python，以便可以在本地预览更改，但这不是强制性的，因为可以在拉取请求过程中生成站点预览（有关更多信息，请参见下文）。有关如何设置 Sphinx 和构建站点的信息，请参阅 README.md。

GitHub 仓库的默认分支只包含网站的「代码」，不包含最终编译结果；每次推送更新时，自动化工具都会编译此源代码，并将编译结果存储在 gh-pages 分支中，通过 https://fortran-lang.org 提供内容。

因此，作为贡献者，你只需上传对站点源码的更改而非编译结果，因为它将通过默认分支上的源码自动构建。

工作流程#

通过对 Github 仓库fortran-lang/webpage发起「拉取请求」来提交你的贡献。

工作流程的形式如下：

  1. 创建/更新 webpage 的个人分支

  2. 在你的 fork 中创建一个新分支

    • 分支名称应简明扼要地描述你的贡献，例如 fix-spelling-homepage, update-compiler-info

  3. 在你的本地分支上进行修改

  4. 将修改后的分支推送到 fork

    • 例如 git push --set-upstream origin fix-spelling-homepage

  5. 从你修改的 fork 分支在 fortran-lang/webpage 中创建拉取请求

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.

注意：你可以在发起「拉取请求」后继续将修改推送到你的 fork 分支 ——「拉取请求」会相应更新

其他社区成员将审查你的「拉取请求」，并可能提出修改要求。 GitHub 在其网站上提供了一个简单的界面，只需单击一个按钮即可接受（或拒绝）审查者建议的修改。你不必手动将修改建议复制到本地副本并再次将其推送。如果你使用了「提交建议」按钮，你需要用 git pull 更新你的计算机上的本地副本，从而推送更多后续的编辑。

一旦你的拉取请求获得批准 —— 通常由至少两个其他社区成员批准，维护人员会将其合并到默认分支中，然后将其发布到 fortran-lang.org 站点。

如有需求，仓库维护人员也会根据你提议的修改构建公开的预览，可在 fortran-lang.org/pr/#pr_id/ 查看，其中 #pr_id 是「拉取请求」的数字标识符。

审查成员从而能够直接查看你的「拉取请求」所生成的结果。

**注意：**如果你将后续提交推送到你的分支，你需要在「拉取请求」中使用#build_preview发表评论来重新构建预览。

合并并成功呈现拉取请求后，工作流将删除预览版本。

**注意：**如果根据你的「拉取请求」所生成的预览链接未能正常工作，或是在重新构建后内容仍未更新，请尝试在 URL 末尾添加一个随机参数，例如 https://fortran-lang.org /pr/98?v=2 —— 参数的名称和值无关紧要，但每次更新须使用不同的值。这会迫使 GitHub 的内容分发网络为你提供更新后的版本，而非过时的缓存版本。

风格指引#

Markdown#

  • 代码片段放在代码块环境中，用反引号（```）包裹。对行内代码片段、编程语言关键字、变量名和文件名则使用行内代码样式（`code`）。

  • 每行源代码不应该超过一个句子，且应将长句分成多行——这能有效避免出现庞大的git diff块，有利于代码审查。

图标集#

图标可以打破单调的文本段落，将读者的注意力引导到标题或关键信息上，提升页面的审美。

在 fortran-lang.org 上可以使用以下三个图标集：

示例： Font awesome

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

示例： Sphinx 设计 Myst 指令

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

你可以访问相应的网站以浏览可用的图标。

页面内容#

为冗长的页面提供页面内容的超链接有助于读者阅读。每个当前页面的目录都能够自动生成。而控制生成 fortran-lang.org 中的整个文件夹的目录的方法是：

对于 MD 格式的页面：

在 md 格式的索引页末尾添加 toctree 指令，其中包含该文件夹中所有文件的名称。

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

教程#

迷你书内容指引。

一般情况#

使用 book 布局。

遵循 Markdown 指南。

代码风格#

缩进使用两个空格，代码单元内部都需要缩进，但是 contains 语句与其所在的 module 或 type 保持同一层级。尽量将一行代码限制在 90 个字符以内。这些考量能让代码更具可读性，也容易在宽度较小的设备上浏览。

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

每个代码片段块都默认以不缩进开始，即使相应代码放在更大的上下文中是应当缩进的。

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

避免刻意将 :: 和行内注释垂直对齐，因为大多数情况下，这样会增加维护负担并且增大每行的长度。

如果含有并非合乎语法的 Fortran 代码，请将其放置在未定义语言的代码块中，以避免因语法高亮显示代表错误的红框。

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

若有利于提高可读性，请放心舍去表达式中的空格，但是一般建议在运算符周围加上空格。

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

通常在逗号后添加一个空格，除非使用短索引值或变量名称进行索引。

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

除了简单索引之外，其它可以省略空格的情况包括：

  • import 中的别名

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

  • 字符串拼接

    print *, 'hello '//'world'

  • 访问派生类型的成员（属性）

    p%x
p%calc_something(a, b)

  • 以关键字传递参数时的 =

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

行内注释的第一个字母要大写，而仅由一个词或者短语组成的行尾注释则不必如此。

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

你可以在 DFTB+ 格式指南 中找到类似的代码风格建议。

文本#

页面和小节的标题仅句首字母大写，而非所有实词首字母大写。

使用 emphasis 强调（*emphasis*/_emphasis_，呈现为斜体）首次引入的关键字/短语。

避免在段落中使用 strong 强调（**strong**，呈现为粗体），因为粗体样式被应用于标题、示例（Example:)、告诫/旁白等。

在适当的情况下使用警告/旁白（note、tip、important）。

  • 要将 ** 注解 ** 添加到 md 文档，请使用：

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

  • 要将 ** 提示 ** 添加到 md 文档，请使用：

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

  • 要将 ** 重要 ** 文本添加到 md 文档中，请使用：

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

推荐使用 Oxford comma（连续逗号），通常能让句子更清晰。

Fortran 快速，有趣，且享有盛名。