このページでは、Google Season of Docs に承認された技術文書作成プロジェクトの詳細について説明します。
プロジェクトの概要
- オープンソースの組織:
- SymPy
- テクニカル ライター:
- Soumi7
- プロジェクト名:
- docstring 間の整合性 - Sympy のドキュメント
- プロジェクト期間:
- 標準期間（3 か月）
プロジェクトの説明
概要 :
Sympy の現状に関するドキュメントとこれまでの作業：
SymPy の公式スタイルガイドの作成作業が完了しました。
Lauren Glattly の GSoD プロジェクトでは、SymPy docstring のスタイルガイドが作成されました。これは、SymPy ドキュメント スタイルガイドで確認できます。
Special サブモジュールと solvers.py ファイルの docstring を編集し、新しいスタイルガイドのガイドラインに一貫して従うようにしました
コードベース全体の他のすべてのドキュメントも、新しいスタイルガイドに準拠するように編集する必要があります。
提案された作業 :
SymPy のほとんどの docstring は、まだ最新のスタイルガイドに従っていません。このプロジェクトの目標は、このガイドに準拠するように SymPy 全体の docstring を更新することです。
プロジェクトについてメンターと話し合いました。ディスカッションのリンクはこちらです。
最新のスタイルガイドに準拠するように sympy のコードベース全体の docstring を編集することは大きなタスクであり、プロジェクトはそれに限定すべきであると判断されました。
このプロジェクトでの私の仕事は、新しいガイドを実装して既存の docstring を更新するとともに、言語の使用や用語など、その他の不一致を収集して対処することです。
既存のサブセクションの順序は、後で変更することも、別のタスクとして指定することもできます。
パラメータに異なる値を渡した場合の結果の違いを示すために、パラメータの追加とともに例を追加しました。
注意点と落とし穴のセクションに、難しい例を追加してください。
貢献: - #17887 : 問題 #17887 に取り組みました。Special サブモジュールに不足しているドキュメント セクションを追加しました。L さんが編集した Specials サブモジュールの一部の関数に、不足している「パラメータと例」セクションを追加しました。Glattly は最新のスタイルガイドに準拠しており、今後の docstring のモデルとして使用できます。
統合された PR へのリンクは、https://github.com/sympy/sympy/pull/19334 です。
- #19591 : 問題 #19591 はドキュメント スタイルガイドを追跡しています。最新のスタイルガイドに準拠するように core.sympify のドキュメントを編集する PR を追加しました。さまざまなパラメータの使用方法について、体系的な説明と例を追加しました。
PR へのリンク: https://github.com/sympy/sympy/pull/19613
プロジェクトの目標
タイムライン 8 月 17 日より前 :
- 組織への拠出を継続します。
- ユーザー ドキュメントと現在のバージョンの sympy について理解を深めます。
- プロジェクトの実施に役立つ手法やスキルを学びます。
コミュニティの結束:（2020 年 8 月 17 日～ 9 月 13 日）
- コミュニケーション チャネルと時間を設定します（時差があるため）。
- 目標を絞り込み、両者で期待値を設定します。
- モジュールの更新順序について説明します。
- 最新のドキュメント スタイルガイドに準拠するように、モジュールの編集順序を確定しました。
ドキュメントの提供期間（2020 年 9 月 14 日～ 2020 年 11 月 30 日）:
毎週達成する目標を設定します。できれば、1 週間に 1 つ以上のモジュールまたはサブモジュールのドキュメントの更新を完了します。
これらのモジュールのすべての主な目標は、不足しているセクションを追加し、最新のスタイルガイドに沿ってドキュメント コメントを再構成することです。パラメータに異なる値を渡した場合に得られる異なる結果を紹介します。注意が必要な結果はすべて、「問題点と注意点」のセクションに追加します。
1 週目（9 月 14 日～ 9 月 21 日）: コア
第 2 週（9 月 22 日～ 9 月 29 日）: 関数 : サブモジュールの組み合わせ
3 週目（9 月 30 日～ 10 月 6 日）: 関数
第 4 週（10 月 7 日～ 10 月 14 日）: シンプル化、暗号通貨
第 5 週（10 月 15 日～ 10 月 21 日）: ディオファントス
週 6（10 月 22 日～ 10 月 29 日）: ホロノミック :オペレーション サブモジュール
7 週目（10 月 30 日～ 11 月 7 日）: 積分モジュール（integrals.integrals）、Meijer G 関数を使用した積分の計算
第 8 週（11 月 8 日～ 11 月 15 日）: 物理学、カテゴリー モジュールの最後に関数、コード生成モジュール、サブモジュール スペシャル
9 週目（11 月 16 日～ 11 月 23 日）: 物理、カテゴリ モジュールの最後にある関数、コード生成モジュール、サブモジュール スペシャル
第 10 週（11 月 24 日～ 11 月 30 日）: 注意事項と落とし穴のセクション
2020 年 11 月 30 日～ 12 月 5 日（UTC 18:00）: 最終プロジェクトの提出とレポートの作成
2020 年 12 月 3 ～ 10 日（UTC 18:00）: プロジェクトの成功とメンターとの連携の経験を提出
ここで説明するモジュールの順序は、メンターとさらに話し合ったうえで変更できます。
メンターからの提案に沿って、まずは簡単に更新できるモジュールをアップデートすることに重点を置き、次に複雑なモジュールに移ります。
なぜこのプロジェクトに適任だとお考えですか？
過去にコンピュータ サイエンスのテクニカル ライティングの経験があり、git と GitHub にも精通しているので、このプロジェクトに適した人物だと思っています。
sympy の最新のスタイルガイドに沿ってドキュメントを更新する PR を送信し、正常に統合されたため、ワークフローに自信があり、定期的に貢献しています。
最初に投稿を始めたときは、いくつかのエラーが発生しました。変更を commit する前に、ようやく毎回テストの実行とドキュメントの作成に慣れました。これは非常に重要なことです。
このプロジェクトに貢献できることを楽しみにしています。