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.dokyumento.jpで提供されます。

したがって、コントリビューターは、サイトのソースコードへの変更をアップロードするだけでよく、コンパイルされた結果をアップロードする必要はありません。これは、デフォルトブランチのソースコードから自動的に構築されるためです。

ワークフロー#

サイトへの貢献は、githubリポジトリへのプルリクエストによって行われます：https://github.com/fortran-lang/webpage/。

それを行うためのワークフローは次の形式を取ります。

  1. webpageの個人フォークを作成/更新します。

  2. フォークに新しいブランチを作成します。

    • ブランチ名は、あなたの貢献を簡潔に説明する必要があります。例： fix-spelling-homepage、update-compiler-info

  3. ローカルブランチで変更を実行します

  4. 変更されたブランチをフォークにプッシュします。

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

  5. 変更されたフォークブランチからfortran-lang/webpageにプルリクエストを作成します。

注：プルリクエストを開く前に、Sphinx（README.mdを参照）を使用して変更をローカルでビルドし、変更が正しくビルドされ、期待どおりにレンダリングされることを確認する必要があります。

注：プルリクエストを開いた後でも、フォークブランチへの変更をプッシュし続けることができます。プルリクエストはそれに応じて更新されます。

あなたのプルリクエストは、変更を要求する可能性のあるコミュニティの他のメンバーによってレビューされます。GitHubは、ボタンをクリックするだけで、レビューアーが提案した変更を適用（または拒否）するための簡単なインターフェースをウェブサイトで提供します。これにより、提案を手動でローカルコピーにコピーして再度プッシュする必要がなくなります。「提案のコミット」ボタンを使用する場合は、コンピューターからさらに編集をプッシュする場合は、git pullを使用してコンピューター上のローカルコピーを更新する必要があります。

通常、少なくとも2人の他のコミュニティメンバーによって承認されると、プルリクエストはメンテナーによってwebpageのデフォルトブランチにマージされ、その時点でfortran-lang.orgサイトに公開されます。

必要に応じて、リポジトリのメンテナーは、提案された変更の公開プレビューを構築できます。これは、fortran-lang.org/pr/<pr_id>/で表示できます。<pr_id>は、プルリクエストの数値識別子です。

これにより、レビュー担当者はPRの生成結果を直接表示できます。

注：プルリクエストブランチに後続のコミットをプッシュする場合は、プルリクエストに「#build_preview」とコメントして、プルリクエストのプレビューを再構築する必要があります。

プルリクエストがマージされ、正常にレンダリングされた後、ワークフローはプレビュービルドを削除します。

注：プルリクエストのプレビューリンクが機能しない場合、または再構築後に更新されない場合は、URLの末尾にランダムなパラメーターを追加してみてください。例： https://fortran.dokyumento.jp/pr/98?v=2 - パラメーターの名前と値は重要ではありませんが、各更新に異なる値を使用してください。これにより、GitHubコンテンツ配信ネットワークは、古いキャッシュバージョンではなく、更新されたバージョンを強制的に提供します。

スタイルガイド#

Markdown#

  • コードブロックにコード抜粋を配置します。これはバックティック（```）で示されます。インラインコード抜粋、プログラミング言語のキーワード、変数名、ファイル名には、インラインコードスタイル（`code`）を使用します。

  • ソースコードの行ごとに1つの文以下にし、長い文を複数の行に分割します。これは、GitHubでの大きなgit diffとコードレビューブロックを回避するために重要です。

アイコンパック#

アイコンは、単調なテキストパッセージを分割したり、見出しや重要な情報に注意を引いたりすることで、ページの美観を向上させる簡単な方法です。

fortran-lang.orgで使用できる3つのアイコンパックがあります。

例：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ディレクティブをmdに追加します。

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

チュートリアル#

ミニブックコンテンツのガイドライン。

一般#

bookレイアウトを使用します。

Markdownガイドラインに従ってください。

コードスタイル#

インデントには2つのスペースを使用し、ユニットの本体はインデントしますが、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

1語または短いフレーズのみで構成される後続のインラインコメントを除き、インラインコメントの最初の文字を大文字にします。

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

これらのコードスタイルの推奨事項は、DFTB+スタイルガイドの推奨事項と似ています。

テキスト#

ページとセクションのタイトルには、タイトルケースではなく、文頭大文字（Sentence case）を使用してください。

重要なキーワード/フレーズを初めて導入する場合、強調する場合などには、強調（*強調*/_強調_、イタリック体で表示）を使用します。

段落内で強調（**強調**、太字で表示）を使用することは避けてください。太字のスタイルは、見出し、例（例：）に注意を引くため、注意/補足タイトルなどに使用されるためです。

必要に応じて、注意/補足（note、tip、important）を使用してください。

  • mdドキュメントにnoteを追加するには、次のように使用します。

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

  • mdドキュメントにtipを追加するには、次のように使用します。

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

  • mdドキュメントにimportantテキストを追加するには、次のように使用します。

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

オックスフォードコンマを含めることを推奨します。通常、物事をより明確にします。

Fortranは高速で、楽しく、有名です。