これはGSoC 2020の一部としての私の最後の投稿と最終報告ですDhall documentation generator

初期問題

dhallは比較的新しい言語です.dhallパッケージの使い方を見る唯一の方法は、コードを手動で検査してコメントを読むことでした.The Dhall Prelude このアプローチの良い例は、図2に示すようにそのヘッダにコメントを追加することですthis 例.いくつかのパッケージにもコメントがありませんので、実際にパッケージを使用する方法を参照するコードを読む必要があります.

主な貢献

私のGSoCプロジェクトの一部としてdhall-docs これは、パッケージの各ファイルに静的解析を実行することにより、HTMLパッケージを取得し、HTMLドキュメントを生成します.ツールには次の機能があります.

dhallファイルを持つフォルダを取り、そのヘッダを抽出し、そのドキュメントをレンダリングするHTMLを出力します.#1845 )

HTML/UIを改良する簡単なCSSとJSでHTMLをレンダリングします.#1848 , #1895 )

インデックスのDALLファイルセクションには、各ファイルの種類(ソースコードから抽出)が含まれます.#1898 )

assert式を抽出し、生成されたHTMLの専用セクションでレンダリングします.#1899 )

コメントの構文仕様は、正しくマークダウンパーサーを使用する前にインデントを処理するために作成されました#1929 )

ソースコードを次の場所に定義(JTD)機能にジャンプします.

インポート式#1959 )

結合バインディング名#1966 )

ラムダ引数名#1982 )

レコード(リテラルと型)フィールド名(#1991 )

上記のリストのprsで概説される仕事の他に、私は以下の技術的な改善を行いましたdhall-docs パッケージ dhall-haskell リポジトリ

加えるgolden tests 生成されたドキュメントがコード変更を通じて保存されるように設定します.#1899 )

ドキュメントの生成Prelude , dhall-kubernetes , とtest demo package のゴールデンテストのセットアップdhall-docs 用途

私が書いたすべてのPRSのリスト dhall-haskell リポジトリを見つけることができますhere
...そして、私はいくつかの上流の変更をDhall Language Standard :

レコードフィールドラベルのテストを追加する#1013 )

と関連する変更dhall-docs パッケージを管理する#1026 , #1053 )

私は、活発に、そして、活発に物事について議論しましたdhall-docs 私のメンターだけでなく、談話投稿を通じて幅広いコミュニティとの行動.最も適切なポストは以下の通りである.

The first discussion about the dhall-docs goals and my introduction to the community

The announcement of the first release of dhall-docs

あなたが談話に関する私のメッセージを見たいならば.ゴーオールゴーゴーhere
...そして、このセクションを終えるために、私のプロジェクトに直接関係していませんが、私はコミュニティ結合期間に関する小さな問題をとることによって、既存のコードベースに慣れました.私はすでにポストでそれについて話しました.
すべてのソースコードを見つけることができますhere . 我々はすでにリリースしているdhall-docs に関してGitHub release とHackage ) しかし、それはすべての機能を含んでいません.待っているthis release PR on the standard 別のリリースを行うためにマージされる dhall-haskell パッケージdhall-docs .

未定の仕事

私たちの作品と比較した場合、私の提案は、欠けているものは以下の通りです.

レンダリングされたソースコードで構文を強調表示します.最初にそれを持っていましたが、定義へのジャンプはソースコードをどのようにレンダリングするかを変更する必要がありました.これを現在で追加することは可能ですfragments JTD関数

ホバーにタイプ.私たちはWIP PR それは良い形であるが、私は完了できませんでした.

ソースコード内の他の場所からコメントを読む.現時点ではdhall-docs ファイルのヘッダーコメントをサポートしているだけで、レコードフィールド、ラムダ、関数型引数などの他の場所に対するサポートを追加するのが良いでしょう.この仕事の最も難しい部分は適切に空白を維持することですwe're making progress .

インポートを含む式の定義へジャンプします.クリックした式が相対的でリモートのインポートである場合、現在のところ、別のURLに移動します.しかし、もの(./Import.dhall).field.deep まだ処理されません、そして、それは本当に役に立ちます.dhallパッケージで見られる一般的なパターンはpackage.dhall パッケージ内のすべてのファイルを含むファイルと、上記の例を使用して、多くのナビゲーション機能を向上させることができます

私はこれらの機能が行われていない悲しいです.私は、より多くの空白を保存するために、Dallパーサーの2、3の改善を作りましたdhall-docs JTDのために必要で、予想通り、より多くの週をとりました.最良の部分は、そこで行われた仕事も修正するために使用できることですlong-standing に関する問題dhall format コマンド.結局は良いトレードオフだった😄

スクリーンショット＆デモパッケージ

生成されたドキュメントがどのように見えるかのスクリーンショットを次に示します.これらは dhall-haskell のためのCI/CD結果dhall-docs サンプルパッケージで実行し、ジョブが最新版で更新されていないため dhall-lang コミット、相対的なインポートのほとんどすべてのリンクが壊れています(dhall-docs 壊れたリンクを報告しません)
Dallプレリュードパッケージインデックス:
Prelude/Bool/package.dhall 内部はサブパッケージであるPrelude そしてそれはすべてのファイルを再エクスポートPrelude/Bool
The Prelude/Bool/fold 抜粋されたヘッダーをマークダウン、アサーション、および定義機能へのジャンプとして示すように、本当に完全です.

でtest demo package レコードフィールドの定義へのジャンプの良い例は「入れ子ラベルで定義へのジャンプ」です

相対的なインポートのリンクを使用して、同じパッケージ内の別の式に移動できます.

最後の思考

私はまだ、私の提案が受け入れられたGSOCチームからのメールを受け取った後、文字通り私の部屋で叫んだことを覚えています.その瞬間からドイツ人は、これらの最後の4ヶ月間に彼が学んだすべてのことを信じていない.
オープンソースプロジェクトの最も重要な部分はそのコミュニティです:それなしで、プロジェクトはちょうどコードの束です.そして、あなたが本当に情熱的でないならば、あるいは、あなたがそれからどんな資金も得ないならば、積極的であることは難しいです.このプログラムのGoogleのイニシアチブは、多くのプロジェクトが彼らの進行中の問題を終えて、発生するツール(例えばDallのような)のために新しい問題を提供するのを助けます.
初めてオープンソースに貢献することは複雑かもしれませんが、一旦それに慣れると、それは本当に簡単です、そして、あなたは多くの利益を得ます:

共同体の一員である

ヘルプあなたの好きな生態系の成長

技術的で非技術的な面であなたの経歴を改善してください

貢献する前に dhall-haskell , 私のハスケル経験は大学プロジェクトから来ました.私は、それらのプロジェクトがOK ish Haskellを使用したと言うことができました:私は本当にそれらを誇りに思います.私は、誰かが私のコードを見直していなかったし、私は多くのことが改善されることができると感じ、私は比較の任意のポイントを持っていなかった.
クローンの時 dhall-haskell そして、私がこれが全く私にとって新しいということを知っていたどんなファイルも開けました.言葉のようなものは全く知られていなかった.以下のようなものでも

{-# LANGUAGE OverloadedStrings #-}

l :: Data.Text.Text
l = "string literal"

初めに私を混乱させたString と互換性があるData.Text.Text ???????), 今は本当に簡単ですが!
ファンクション、Application、およびMonads(私自身を実装してさえ)で適切に働くこと!私がそんなに多くの時間前にしたかったことであった、そして、倉庫のカップルのカップルの後、本当に自然(まだプロでないと感じ始めました).
私は、不正な状態を表現できないようにするために、より多くのデータ型を作り始めましたMaybe and [] 私の古いプロジェクトとレンズでは、私はそれらをたくさん使用しなかったがdhall-docs , 私を怖がらせるために立ち止まりました.
私が書くことができたより多くのものがあります、しかし、私は現在このポストより長くそれを望みません.
これはGSOCプログラムの私の仕事の終わりですが、私は、私は今後の将来に貢献し続けることをかなり確信しています

謝辞

メンターにGabriel , Simon and Philip : すべてのプロジェクトについて、常にあなたの忍耐のために、機会のために、感謝します.開発のご案内に感謝dhall-docs そして、オープンソースであなたの経験について話すために.
Dallコミュニティに、私のオープン質問に対する彼らの反応に率先してください.
To Haskell.org プロジェクトをホスティングし、どのプロジェクトを選択するか決める😉
そして、最後ではなく、少なくとも:GoogleにGSOCプログラムを提供するために.それはあなたのキャリアを改善し、オープンソースのコミュニティが大きく成長するのに役立つ本当に良い方法です.
感謝❤️