Questa pagina contiene i dettagli di un progetto di scrittura tecnica accettato per Google Season of Docs.
Riepilogo del progetto
- Organizzazione open source:
- SymPy
- Technical writer:
- Soumi7
- Nome progetto:
- Coerenza nelle docstring - Documentazione di Sympy
- Durata del progetto:
- Durata standard (3 mesi)
Project description
Riassunto :
Stato attuale della documentazione di Sympy e lavoro precedente :
Il lavoro di creazione di una guida di stile ufficiale per SymPy è terminato.
Il progetto GSoD di Lauren Glattly ha creato una guida di stile per le docstring SymPy, disponibile nella pagina SymPy documentation Style Guide.
I docstring nel sottomodule Special e nel file resolvers.py sono stati modificati in modo da seguire costantemente le linee guida della nuova guida di stile
Anche tutti gli altri docstring nel codebase dovevano essere ancora modificati per rispettare la nuova guida di stile.
Lavoro proposto :
La maggior parte dei docstring in SymPy continua a non seguire la guida di stile più recente. L'obiettivo di questo progetto è aggiornare i docstring in SymPy per rispettare questa guida.
Ho discusso del progetto con i mentori. Ecco un link alla discussione.
È stato deciso che modificare le docstring in tutto il codebase di sympy per aderire alla più recente guida di stile è un compito importante e il progetto dovrebbe essere limitato a questo.
Il mio lavoro sul progetto prevedeva l'implementazione della nuova guida per aggiornare le docstring esistenti, raccogliendo e risolvendo altre incoerenze come l'uso della lingua o i termini.
L'ordine delle sottosezioni esistenti può essere modificato o deciso in un secondo momento o come attività separata.
Dimostrazione delle differenze nei risultati quando valori diversi vengono trasmessi ai parametri mediante l'aggiunta di altri esempi e della sezione dei parametri.
Continua ad aggiungere esempi complessi alla sezione con suggerimenti e insidie.
Contributi: - #17887 : Si è lavorato sul problema #17887: Aggiunta di sezioni docstring mancanti nel sottomodulo Special. Ho aggiunto la sezione Parametri ed esempi mancanti in alcune funzioni del sottomodulo Speciali che è stato modificato da L. Seguire la guida di stile più recente e fungere da modello per le docstring future.
Ecco il link al mio PR unito : https://github.com/sympy/sympy/pull/19334
- #19591 : Il numero 19591 tiene traccia della guida di stile Documentazione. Ho aggiunto un PR per modificare la docstring core.sympify in modo che aderisca all'ultima guida di stile. Ho aggiunto spiegazioni strutturate ed esempi sull'utilizzo di diversi parametri.
Ecco il link al PR: https://github.com/sympy/sympy/pull/19613
Obiettivi del progetto
Cronologia Prima del 17 agosto :
- Continua a dare contributi all'organizzazione.
- Acquisisci maggiore familiarità con la documentazione per l'utente e la versione corrente di sympy.
- Acquisisci tecniche e competenze che ti saranno utili durante l'implementazione del progetto.
Legami comunitari : (17 agosto - 13 settembre 2020)
- Impostare un canale di comunicazione e un orario (a causa della differenza di tempo).
- Perfezionare gli obiettivi e creare aspettative da entrambe le parti.
- Discussione sull'ordine in cui i moduli verranno aggiornati.
- Finalizza l'ordine di modifica dei moduli per farli rispettare la guida di stile docstring più recente.
Periodo della documentazione(14 settembre 2020 - 30 novembre 2020) :
Imposta gli obiettivi da raggiungere ogni settimana, preferibilmente completando l'aggiornamento delle docstring di un modulo o di un sottomodulo alla settimana o più.
Per tutti questi moduli, il mio obiettivo principale sarà aggiungere sezioni mancanti e riorganizzare le docstring in modo da seguire la guida di stile più recente. Ciò include la dimostrazione dei diversi risultati ottenuti quando vengono trasmessi valori diversi ai parametri. Tutti gli output difficili saranno aggiunti alla sezione Gotcha e errori.
Settimana 1 ( 14 settembre - 21 settembre) : Principale
Settimana 2 (22 settembre - 29 settembre) : Funzioni : Sottomoduli Combinatoria
Settimana 3 (30 settembre - 6 ottobre) : Funzioni
Settimana 4 (7 ottobre - 14 ottobre) : Semplifica, Crypto
Settimana 5 (15 - 21 Ottobre) : Diofantee
Settimana 6 (22 ottobre - 29 ottobre):Holonomic :Sottomodulo delle operazioni
Settimana 7 (30 ottobre - 7 novembre) : Integrals Module(integrals.integrals), Computing Integrals using Meijer G-Functions
Settimana 8 (8 novembre - 15 novembre) : Fisica, Funzioni alla fine del Modulo relativo alle categorie, Modulo di generazione del codice, Sottomodulo Speciale
Settimana 9 (16 novembre - 23 novembre) : Fisica, Funzioni alla fine del Modulo Categorie, Modulo di Generazione del Codice, Sottomodulo Speciale
Settimana 10 (24 novembre - 30 novembre) : sezione Gotchas e Trabocchetti
30 novembre - 5 dicembre 2020 alle 18:00 UTC : invio finale del progetto e scrittura del report
3 - 10 dicembre 2020 alle 18:00 UTC : invio del successo del progetto e dell'esperienza di lavoro con i mentori
L'ordine dei moduli menzionati qui può essere modificato dopo ulteriori discussioni con i mentori.
Come suggerito dai mentori, mi concentrerò sull'aggiornamento dei moduli più semplici da aggiornare, per poi passare a quelli più complessi.
Perché sono la persona giusta per questo progetto?
Credo di essere la persona giusta per questo progetto perché ho passato esperienza in scrittura tecnica con l'informatica e sono ben preparata con Git e GitHub.
Dato che ho inviato dei PR per aggiornare la documentazione all'ultima guida di stile in sympy, che è stata unita correttamente, ho fiducia nel flusso di lavoro e contribuisco regolarmente.
Quando ho iniziato a contribuire, ho riscontrato alcuni errori. Finalmente mi sono abituato a eseguire i test e a creare i documenti ogni volta prima di eseguire il commit delle modifiche, dato che è molto importante.
Mi sento a mio agio nel contribuire a questo progetto e non vedo l'ora che diventi disponibile.