为 fortran-lang.org 贡献内容#

Fortran-lang.org 是开源的，欢迎贡献！

请参阅软件包索引指南，了解如何向软件包索引添加条目。
请参阅迷你教程指南，了解如何为学习部分撰写和构建迷你教程。

简介#

网站是如何编写的？

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

该网站是静态的，这意味着一旦构建完成，网站上的内容对所有用户都是相同的；这与许多动态网站形成对比，动态网站可以根据用户和用户提供的输入提供不同的内容。

网站的结构组件使用 Sphinx 静态网站生成器来实现静态功能，并使用 JavaScript 来实现动态功能。

我需要了解 HTML 才能贡献吗？

网站的大部分内容都是使用 Markdown 编写的，这是一种用于格式化文本的简单标记语言 - 如果您以前从未使用过它，请不要担心，它非常容易上手！

网站是如何构建的？

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

GitHub 存储库的默认分支仅包含网站的“源代码”，而不包含最终编译结果；每次推送更新时，自动服务都会编译此源代码，并将编译结果存储在 gh-pages 分支上，该分支在 https://fortran-lang.cn 上提供服务。

因此，作为贡献者，您只需将更改上传到网站源代码，而无需上传编译结果，因为这是从默认分支上的源代码自动构建的。

工作流程#

对网站的贡献是通过向 github 存储库提交拉取请求来完成的：https://github.com/fortran-lang/webpage/。

执行此操作的工作流程采用以下形式

创建/更新网页的个人 fork。
- (请参阅 github 帮助：同步 fork )
在您的 fork 中创建一个新分支。
- 分支名称应简洁地描述您的贡献，例如 fix-spelling-homepage、update-compiler-info
在本地分支上执行您的更改。
将您修改的分支推送到您的 fork。
- 例如 git push --set-upstream origin fix-spelling-homepage
从您修改的 fork 分支向 fortran-lang/webpage 创建一个拉取请求。
- (请参阅 github 帮助：创建拉取请求 )

注意：在打开拉取请求之前，您必须使用 Sphinx 在本地构建您的更改（请参阅 README.md），以验证您的更改是否正确构建并按预期呈现。

注意：在打开拉取请求后，您可以继续将更改推送到您的 fork 分支 - 拉取请求将相应更新。

您的拉取请求将由社区的其他成员审查，他们可能会要求您进行更改。GitHub 在其网站上提供了一个简单的界面，只需点击一个按钮即可应用（或拒绝）任何审阅者建议的更改。这避免了必须手动将建议复制到您的本地副本并再次推回。如果您使用“提交建议”按钮，则如果打算从您的计算机推送更多编辑，则需要使用 git pull 更新计算机上的本地副本。

一旦您的拉取请求获得批准（通常由至少两名其他社区成员批准），维护人员就会将其合并到网页默认分支中，此时它将发布到 fortran-lang.org 网站。

如果需要，存储库维护人员可以构建您建议更改的公共预览，该预览可在 fortran-lang.org/pr/<pr_id>/ 处查看，其中 <pr_id> 是您的拉取请求的数字标识符。

这允许审阅者直接查看您的 PR 生成的结果。

注意：如果您随后将提交推送到您的拉取请求分支，则必须通过在拉取请求中添加“#build_preview”评论来重新构建拉取请求预览。

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

注意：如果您的拉取请求预览链接无法正常工作或在重新构建后未更新，请尝试在 URL 末尾添加一个随机参数，例如 https://fortran-lang.cn/pr/98?v=2 - 参数的名称和值无关紧要，但每次更新都使用不同的值。这将强制 GitHub 内容交付网络为您提供更新的版本，而不是过时的缓存版本。

样式指南#

Markdown#

将代码摘录放在代码块中，由反引号 (```) 表示。对于内联代码摘录、编程语言关键字、变量名称和文件名，使用内联代码样式 (`code`)。
每行源代码最多包含一个句子，并将长句子分解成多行 - 这对于避免在 github 上出现大型 git diff 和代码审查块非常重要。

外部链接#

建议的做法是在新标签页中打开外部超链接。在 Fortran-lang.org 上，所有此类链接都将自动添加新标签页图标；这使网站用户预先预期链接将引导他们离开网站，同时保持 fortran-lang.org 在之前的标签页中打开。

示例：在新标签页中打开链接（HTML 或 markdown）

<a href="https://fortran-lang.discourse.group/" target="_blank" rel="noopener"
  >Discourse</a
>

内部网站链接#

指向 fortran-lang.org 网站其他部分的超链接应以 {{pathto('index',1)[:-5]}} 为前缀 - 这对于生成拉取请求预览非常重要（有关说明，请参阅此处）。

示例：markdown 链接

[Fortran-lang news]({{pathto('index',1)[:-5]}}News)

示例：html 链接

<a href="{{pathto('index',1)[:-5]}}Packages">Fortran packages</a>

图标包#

图标是通过分解单调的文本段落并提请注意标题或关键信息，从而轻松改进页面美观的简便方法。

fortran-lang.org 上可以使用三个图标包。

Sphinx-design（MIT 许可证）
Font awesome（CC BY 4.0 许可证）

示例：Font awesome

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

示例：Sphinx design Myst 指令

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

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

页面内容#

对于较长的页面，显示超链接的页面内容有时会很有帮助。页面 TOC 树已自动化，并将生成当前页面的 TOC。而生成 Fortran-lang.org 上整个目录的 TOC 的方法是

对于 MD 中的页面

在目录的索引页末尾添加 toc tree 指令，其中包含该目录中所有文件的名称。

````{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

每个代码块都应具有 0 的基本缩进级别，即使将其放入更大的上下文中也会缩进。

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

除了简单的索引之外，其他可以省略空格的情况

导入中的别名

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_，渲染为斜体）。

避免在段落中使用粗体（**strong**，渲染为粗体），因为粗体样式用于标题、突出显示示例（示例：）、警告/旁注标题等。

在适当的情况下，使用警告/旁注（注意、提示、重要）。

要向 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.
:::::

建议使用牛津逗号。它通常使事情更清晰。

Fortran 速度快、有趣且闻名。

站点预览：您正在预览 的未发布更改。