このページには、Google シーズンの Google ドキュメントで承認されたテクニカル ライティング プロジェクトの詳細が記載されています。
プロジェクトの概要
- オープンソースの組織:
- SymPy
- テクニカル ライター:
- Soumi7
- プロジェクト名:
- docstring 間の整合性 - Sympy ドキュメント
- プロジェクトの期間:
- 標準の長さ（3 か月）
プロジェクトの説明
概要 :
現状の Sympy のドキュメントとこれまでの作業 :
SymPy の公式スタイルガイドの作成作業はこれで完了です。
Lauren Glattly の GSoD プロジェクトは、SymPy ドキュメント スタイル ガイドにある SymPy docstring のスタイルガイドを作成しました。
新しいスタイルガイドのガイドラインに一貫して準拠するように、Special サブモジュールと resolvers.py ファイルの docstring を編集しました。
コードベース全体の他のすべての docstring も、新しいスタイルガイドに合わせて編集する必要があります。
提出する課題 :
SymPy のほとんどの docstring は、最新のスタイルガイドに従っていません。このプロジェクトの目標は、このガイドに従うように SymPy 全体の docstring を更新することです。
そのプロジェクトについてメンターと話し合いました。こちらがディスカッションへのリンクです。
最新のスタイルガイドに準拠するために sympy のコードベース全体で docstring を編集する作業は大変な作業であり、プロジェクトはその作業に限定すべきであると判断されました。
このプロジェクトでは、新しいガイドを実装して既存の docstring を更新すると同時に、言語の使い方や用語といったその他の不一致を収集して対処します。
既存のサブセクションの順序は、後で、または個別のタスクとして、変更または決定できます。
パラメータに異なる値が渡される場合の結果の違いを、パラメータ セクションの追加とともに例を追加して示します。
問題点と落とし穴のセクションに、ややこしい例を追加していきましょう。
投稿: - #17887 : 問題 #17887 に対応: 特殊なサブモジュールに欠落していた docstring セクションを追加。L が編集した Specials サブモジュールの一部の関数に、欠落していたパラメータと例のセクションを追加しました。Glattly は最新のスタイルガイドに従い、今後の docstring のモデルとして機能します。
結合された PR へのリンクは次のとおりです。 https://github.com/sympy/sympy/pull/19334
- #19591 : 問題 #19591 は、ドキュメントのスタイルガイドを追跡します。最新のスタイルガイドに従って core.sympify docstring を編集するための PR を追加しました。さまざまなパラメータの使用法について、構造化された説明と例を追加しました。
PR へのリンクはこちら: https://github.com/sympy/sympy/pull/19613
プロジェクトの目標
スケジュール 8 月 17 日より前 :
- 組織への貢献を継続する。
- ユーザー ドキュメントと sympy の現行バージョンを十分に理解します。
- プロジェクトの実施に役立つ手法やスキルを学ぶことができます。
コミュニティの絆（2020 年 8 月 17 日～ 9 月 13 日）
- コミュニケーション チャネルと時間（時差による）を設定します。
- 目標を絞り込んで、双方に期待値を設定する。
- モジュールの更新順序
- モジュールの編集順序を最終決定して、最新の docstring スタイルガイドに従うようにします。
証拠書類作成期間（2020 年 9 月 14 日～ 2020 年 11 月 30 日）：
毎週達成する目標を設定します。可能であれば、1 週間に 1 つ以上のモジュールまたはサブモジュールの docstring の更新を完了します。
これらすべてのモジュールについて、主な目標は、欠落しているセクションを追加し、最新のスタイルガイドに沿って docstring を再構築することです。これには、パラメータに異なる値を渡したときに得られる結果が異なることを説明することも含まれます。難しい出力はすべて、「問題点」と「問題点」セクションに追加します。
第 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 日 18:00（UTC）: プロジェクトの最終提出およびレポートの作成
2020 年 12 月 3 日～ 10 日、18:00（UTC） : プロジェクトの実績とメンターとの共同作業経験の提出
ここに記載されているモジュールの順序は、メンターとの話し合いの後で変更できます。
メンターからすすめられたように、まずは更新しやすいモジュールを優先的に更新してから、複雑なモジュールに進みます。
私がこのプロジェクトの適任者である理由
私は、コンピュータ サイエンスのテクニカル ライティングに関する経験があり、git と GitHub にも精通しているので、このプロジェクトの適任者であると確信しています。
ドキュメントを Cymbal の最新のスタイルガイドに更新するよう PR に提出したところ、正常に統合されました。このワークフローには自信があり、定期的に投稿を行っています。
投稿を始めた当初、いくつかのエラーが発生しました。ようやくテストの実行やドキュメントの構築に慣れてから、変更を commit できるようになりました。これはとても重要なことです。
このプロジェクトに貢献できることを非常に楽しみにしています。