Cette page contient les détails d'un projet de rédaction technique accepté pour la saison des documents Google.
Résumé du projet
- Organisation Open Source:
- SymPy
- Rédacteur technique:
- Soumi7
- Nom du projet:
- Cohérence entre les docstrings : documentation Sympy
- Durée du projet:
- Durée standard (trois mois)
Project description
Résumé :
État actuel de la documentation de Sympy et des travaux antérieurs :
La création d'un guide de style officiel pour SymPy est terminée.
Le projet GSoD de Lauren Glattly a créé un guide de style pour les docstrings SymPy, disponible sur le site SymPy Documentation Style Guide.
Les docstrings du sous-module Special et du fichier solvers.py ont été modifiés pour suivre de manière cohérente les consignes du nouveau guide de style.
Toutes les autres docstrings du codebase devaient encore être modifiées pour respecter le nouveau guide de style.
Travail proposé :
La plupart des docstrings de SymPy ne respectent toujours pas le dernier guide de style. L'objectif de ce projet est de mettre à jour les docstrings dans SymPy afin de respecter ce guide.
J'ai discuté du projet avec des mentors. Voici un lien vers la discussion.
Il a été décidé que la modification des docstrings dans le codebase de sympy pour respecter le dernier guide de style était une tâche ardue et que le projet devrait se limiter à cette tâche.
Mon travail sur le projet consisterait à mettre en œuvre le nouveau guide pour mettre à jour les docstrings existantes, tout en collectant et en traitant d'autres incohérences telles que l'utilisation du langage ou les termes.
L'ordre des sous-sections existantes peut être modifié ou décidé ultérieurement ou en tant que tâche distincte.
Illustration des différences de résultats lorsque différentes valeurs sont transmises aux paramètres en ajoutant d'autres exemples et une section sur les paramètres.
Continuez à ajouter des exemples difficiles à la section "Pièges et écueils".
Contributions : - #17887 : Travaillé sur le problème 17887: Ajout des sections de docstring manquantes dans le sous-module spécial. J'ai ajouté la section "Paramètres et exemples" manquante dans certaines fonctions du sous-module Specials, qui a été modifiée par L. Glattly pour suivre le dernier guide de style et servir de modèle pour les futures docstrings.
Voici le lien vers ma demande de fusion : https://github.com/sympy/sympy/pull/19334.
- #19591 : le problème n° 19591 suit le guide de style de la documentation. J'ai ajouté une demande de pull pour modifier la docstring de core.sympify afin de respecter le dernier guide de style. J'ai ajouté des explications structurées et des exemples sur l'utilisation des différents paramètres.
Voici un lien vers la demande de publication: https://github.com/sympy/sympy/pull/19613
Objectifs du projet
Calendrier Avant le 17 août :
- Continuez à contribuer à l'organisation.
- Familiarisez-vous avec la documentation utilisateur et la version actuelle de sympy.
- Découvrez les techniques et les compétences qui vous seront utiles lors de la mise en œuvre du projet.
Liens communautaires (du 17 août au 13 septembre 2020)
- Mettez en place un canal de communication et un délai (en raison du décalage horaire).
- affiner mes objectifs et définir des attentes des deux côtés ;
- Discuter de l'ordre dans lequel les modules seront mis à jour.
- Finalisez l'ordre des modules de modification afin qu'ils respectent le dernier guide de style des docstrings.
Période de documentation(14 septembre 2020 – 30 novembre 2020) :
Définissez des objectifs à atteindre chaque semaine. Idéalement, mettez à jour les docstrings d'un module ou d'un sous-module par semaine ou plus.
Pour tous ces modules, mon objectif principal sera d'ajouter les sections manquantes et de restructurer les docstrings pour qu'ils respectent le dernier guide de style. Cela inclura la démonstration des différents résultats obtenus lorsque différentes valeurs sont transmises aux paramètres. Tous les éléments de sortie problématiques doivent être ajoutés à la section "Codes et pièges".
Semaine 1 ( 14 septembre – 21 septembre) : zone principale
Semaine 2 (22 au 29 septembre) : Fonctions : sous-modules combinatoires
Semaine 3 (30 septembre-6 octobre) : fonctions
Semaine 4 (7 octobre - 14 octobre) : Simplifier, crypto
Semaine 5 (15 octobre – 21 octobre) : équations diophantines
Semaine 6 (22 octobre – 29 octobre):Holonomie :sous-module "Opérations"
Semaine 7 (30 octobre - 7 novembre) : module Integrals(integrals.integrals), calcul des intégrales à l'aide des fonctions G de Meijer
Semaine 8 (8 novembre - 15 novembre) : Physique, Fonctions à la fin du module sur les catégories, Module de génération de code, Sous-module spécial
Semaine 9 (16 novembre - 23 novembre) : Physique, Fonctions à la fin du module sur les catégories, Module de génération de code, Sous-module spécial
Semaine 10 (24 novembre au 30 novembre) : section "Pièges et écueils"
Du 30 novembre au 5 décembre 2020 à 18h (UTC) : soumission du projet final et rédaction du rapport
3 au 10 décembre 2020 à 18h UTC : présentation du succès du projet et de l'expérience de travail avec les mentors
L'ordre des modules mentionnés ici peut être modifié après une discussion plus approfondie avec les mentors.
Comme suggéré par mes mentors, je vais d'abord me concentrer sur la mise à jour des modules les plus faciles à modifier, puis passer aux plus complexes.
Pourquoi suis-je la personne idéale pour ce projet ?
Je pense être la personne idéale pour ce projet, car j'ai de l'expérience en rédaction technique en informatique et je maîtrise bien Git et GitHub.
J'ai envoyé des PR pour mettre à jour la documentation avec le dernier guide de style dans sympy, qui ont été fusionnés avec succès. Je suis donc à l'aise avec le workflow et je contribue régulièrement.
Au début, lorsque j'ai commencé à contribuer, j'ai rencontré des erreurs. Je me suis enfin habitué à exécuter les tests et à créer les documents à chaque fois avant de valider les modifications, car c'est très important.
Je suis très à l'aise pour contribuer à ce projet et j'ai hâte de le faire.