Diese Seite enthält die Details zu einem Projekt für technisches Schreiben, das für die Google-Produktsaison von Google Docs akzeptiert wurde.
Projektzusammenfassung
- Open-Source-Organisation:
- SymPy
- Technischer Redakteur:
- Soumi7
- Projektname:
- Konsistenz in Docstrings – Sympy-Dokumentation
- Projektdauer:
- Standarddauer (3 Monate)
Projektbeschreibung
Zusammenfassung :
Aktueller Stand der Sympy-Dokumentation und vorherigen Arbeiten :
Die Erstellung eines offiziellen Styleguides für SymPy ist abgeschlossen.
Im GSoD-Projekt von Lauren Glattly wurde ein Styleguide für SymPy-Docstrings erstellt, den Sie im SymPy Documentation Style Guide finden.
Die Dateien „docstrings“ im untergeordneten Modul „Special“ und in der Datei „solvers.py“ wurden so bearbeitet, dass sie den Richtlinien des neuen Styleguides entspricht.
Alle anderen docstrings auf der Codebasis mussten noch bearbeitet werden, damit sie ebenfalls dem neuen Styleguide entsprechen.
Vorgeschlagenes Werk :
Die meisten Docstrings in SymPy entsprechen immer noch nicht dem neuesten Styleguide. Das Ziel dieses Projekts wäre es, die Docstrings in SymPy zu aktualisieren, damit sie dieser Anleitung entsprechen.
Ich habe das Projekt mit den beratenden Personen besprochen. Hier ist der Link zur Diskussion.
Es wurde beschlossen, dass das Bearbeiten von docstrings in der gesamten Codebasis von sympy zur Einhaltung des neuesten Styleguides eine große Aufgabe ist und das Projekt darauf beschränkt werden sollte.
Meine Arbeit an diesem Projekt würde die Implementierung des neuen Leitfadens zur Aktualisierung vorhandener Docstrings beinhalten, während ich andere Inkonsistenzen wie Sprachgebrauch oder Begriffe erfasse und behebe.
Die Reihenfolge vorhandener Unterabschnitte kann später oder als separate Aufgabe geändert oder festgelegt werden.
Die Unterschiede in den Ergebnissen, wenn verschiedene Werte an Parameter übergeben werden, indem Sie weitere Beispiele und den Abschnitt „Parameter“ hinzufügen.
Fügen Sie weiter knifflige Beispiele in den Abschnitt mit Fallstricken und Fallstricken hinzu.
Beiträge: - #17887 : Hat an Problem Nr. 17887 mitgearbeitet: Fehlende docstring-Abschnitte im speziellen Untermodul hinzugefügt. Ich habe den fehlenden Abschnitt „Parameter und Beispiele“ bei einigen Funktionen des Submoduls „Sonderangebote“ hinzugefügt, das von L bearbeitet wurde. Befolgen Sie gerne den neuesten Styleguide und dienen Sie als Modell für zukünftige Docstrings.
Hier ist der Link zu meiner zusammengeführten PR : https://github.com/sympy/sympy/pull/19334
- #19591 : Problem Nr. 19591 verfolgt den Styleguide für die Dokumentation. Ich habe einen PR hinzugefügt, um den Docstring „core.sympify“ zu bearbeiten, damit er dem neuesten Styleguide entspricht. Ich habe strukturierte Erläuterungen und Beispiele zur Verwendung verschiedener Parameter hinzugefügt.
Über diesen Link gelangen Sie zum PR: https://github.com/sympy/sympy/pull/19613
Projektziele
Zeitplan Vor dem 17. August :
- Sie können weiterhin zur Organisation beitragen.
- Machen Sie sich mit der Nutzerdokumentation und der aktuellen Version von sympy vertraut.
- Sie erlernen Techniken und Fähigkeiten, die bei der Umsetzung des Projekts hilfreich sein werden.
Community-Bonding : (17. August bis 13. September 2020)
- Legen Sie einen Kommunikationskanal und eine Uhrzeit fest (aufgrund des Zeitunterschieds).
- meine Ziele zu optimieren und Erwartungen auf beiden Seiten zu wecken.
- Besprechen der Reihenfolge, in der die Module aktualisiert werden.
- Die Reihenfolge der Bearbeitungsmodule abschließen, damit sie dem neuesten docstring-Styleguide entsprechen.
Dokumentationszeitraum(14. September 2020 bis 30. November 2020) :
Setzen Sie sich Ziele, die jede Woche erreicht werden sollen, und aktualisieren Sie vorzugsweise die Docstrings eines Moduls oder Untermoduls pro Woche oder mehr.
Bei allen diesen Modulen besteht mein Hauptziel darin, fehlende Abschnitte hinzuzufügen und die Docstrings so umzustrukturieren, dass sie dem neuesten Styleguide entsprechen. Dabei werden auch die verschiedenen Ergebnisse aufgezeigt, die erzielt werden, wenn verschiedene Werte an die Parameter übergeben werden. Alle kniffligen Ausgaben werden dem Abschnitt „Erkenntnisse und Fallstricke“ hinzugefügt.
Woche 1 ( 14. September–21. September) : Grundumsatz
Woche 2 (22. September - 29. September) : Funktionen : Kombinatorische Untermodule
Woche 3 (30. September bis 6. Oktober) : Funktionen
Woche 4 (7. Oktober–14. Oktober) : Vereinfachen, Krypto
Woche 5 (15. Oktober–21. Oktober) : Diophantin
Woche 6 (22. Oktober–29. Oktober):Holonomische :Operations-Submodul
7. Woche (30. Oktober - 7. November) : Integrals Module(integrals.integrals), Computing Integrals using Meijer G-Functions
8. Woche (8. November bis 15. November) : Physik, Funktionen am Ende des Kategorien-Moduls, Modul zur Codegenerierung, Spezial-Submodul
Woche 9 (16. November - 23. November) : Physik, Funktionen am Ende des Kategorien-Moduls, Modul zur Codegenerierung, Spezial-Submodul
10. Woche (24. November - 30. November) : Abschnitt „Alles Wissenswerte und Fallstricke“
30. November bis 5. Dezember 2020 um 18:00 Uhr (UTC): Endgültige Projekteinreichung und Verfassen von Berichten
3.–10. Dezember 2020 um 18:00 Uhr (UTC): Projekterfolg und Erfahrungen aus der Arbeit mit Mentoren einreichen
Die Reihenfolge der hier genannten Module kann nach weiteren Rücksprache mit den beratenden Personen geändert werden.
Wie von Mentoren vorgeschlagen, werde ich mich zuerst darauf konzentrieren, diese Module zu aktualisieren, die einfacher zu aktualisieren sind, und dann mit den komplexen Modulen fortfahren.
Warum bin ich die richtige Person für dieses Projekt?
Ich glaube, ich bin die richtige Person für dieses Projekt, da ich Erfahrung im technischen Schreiben mit Informatik und gute Kenntnisse mit Git und GitHub habe.
Da ich PRs zur Aktualisierung der Dokumentation über den neuesten Styleguide in Sympy eingereicht habe, die erfolgreich zusammengeführt wurden, bin ich mit dem Workflow und den regelmäßigen Beiträgen sicher.
Als ich anfing, Beiträge zu verfassen, traten einige Fehler auf. Ich habe mich endlich daran gewöhnt, die Tests durchzuführen und die Dokumente jedes Mal zu erstellen, bevor ich die Änderungen übernommen habe, da das sehr wichtig ist.
Ich bin sehr wohl dabei, einen Beitrag zu diesem Projekt zu leisten, und freue mich darauf.