Cette page contient les détails d'un projet de rédaction technique accepté pour Google Season of Docs.
Résumé du projet
- Organisation Open Source:
- SymPy
- Rédacteur technique:
- Soumi7
- Nom du projet:
- Cohérence entre les chaînes de document : documentation Sympy
- Durée du projet:
- Durée standard (3 mois)
Project description
Extrait :
État actuel de la documentation Sympy et travaux antérieurs :
Le travail de création d'un guide de style officiel pour SymPy est terminé.
Le projet GSoD de Lauren Glattly a créé un guide de style pour les chaînes de document SymPy. Vous le trouverez dans le guide de style de la documentation SymPy.
Les docstrings du sous-module spécial et du fichier resolvers.py ont été modifiés de manière à respecter systématiquement les consignes du nouveau guide de style.
Toutes les autres chaînes de document du codebase devaient encore être modifiées pour respecter le nouveau guide de style.
Tâche proposée :
La plupart des docstrings de SymPy ne suivent toujours pas le dernier guide de style. L'objectif de ce projet est de mettre à jour les docstrings de SymPy pour qu'elles soient conformes à 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 tout le codebase de sympy afin de respecter le dernier guide de style était une tâche ardue et le projet devait s'y limiter.
Mon travail sur le projet consisterait à mettre en œuvre le nouveau guide pour mettre à jour les documents existants, tout en collectant et en corrigeant 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 sous la forme d'une tâche distincte.
Démontrer les différences dans les résultats lorsque différentes valeurs sont transmises aux paramètres en ajoutant des exemples et en ajoutant une section de paramètres.
Continuez à ajouter des exemples délicats dans la section des pièges et pièges.
Contributions : - #17887 : Résolution du problème n° 17887: Ajout de sections docstring manquantes dans un sous-module spécial. J'ai ajouté la section "Paramètres et exemples" manquante dans certaines fonctions du sous-module Promotions qui a été modifiée par L. Nous vous invitons à suivre le guide de style le plus récent et à vous servir de modèle pour vos futures chaînes de document.
Voici le lien vers mon PR fusionné : https://github.com/sympy/sympy/pull/19334
- #19591 : le problème n° 19591 correspond au guide de style de la documentation. J'ai ajouté un PR pour modifier la chaîne de document core.sympify afin qu'elle respecte le dernier guide de style. J'ai ajouté des explications structurées et des exemples d'utilisation de différents paramètres.
Voici le lien vers le PR: https://github.com/sympy/sympy/pull/19613
Objectifs du projet
Calendrier Avant le 17 août :
- Continuer à contribuer à l'organisation.
- Familiarisez-vous avec la documentation utilisateur et la version actuelle de sympy.
- Apprendre des techniques et des compétences qui seront utiles lors de la mise en œuvre du projet.
Engagement avec une communauté : (17 août-13 septembre 2020)
- Mettre en place un canal de communication et un horaire (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 d'édition des modules pour qu'ils respectent le dernier guide de style des chaînes de document.
Période de documentation(du 14 septembre 2020 au 30 novembre 2020) :
Définissez des objectifs à atteindre chaque semaine, de préférence terminer la mise à jour des chaînes de document d'un module ou d'un sous-module par semaine ou plus.
Pour tous ces modules, mon objectif principal est d'ajouter les sections manquantes et de restructurer les docstrings conformément au dernier guide de style. Cela inclura la démonstration des différents résultats obtenus lorsque différentes valeurs sont transmises aux paramètres. Toutes les sorties difficiles doivent être ajoutées à la section Gotchas and Pitfalls (en anglais).
Semaine 1 ( 14 septembre - 21 septembre) : Core
Semaine 2 (22 septembre - 29 septembre) : Fonctions : sous-modules combinatoires
Semaine 3 (30 septembre - 6 octobre) : Fonctions
Semaine 4 (7 octobre - 14 octobre) : Simplifier, crypter
Semaine 5 (15 octobre - 21 octobre) : diophantine
Semaine 6 (22 - 29 octobre):Sous-module Holonomic :Opérations
Semaine 7 (30 octobre - 7 novembre) : Module des intégrales(integrals.integrals), calcul d'intégrales à l'aide des fonctions G de Meijer
Semaine 8 (8 novembre - 15 novembre) : physique, fonctions à la fin du module "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 "Catégories", module de génération de code, sous-module spécial
Semaine 10 (24 novembre - 30 novembre) : section "Gotchas et pièges"
Du 30 novembre au 5 décembre 2020 à 18h UTC : envoi du projet final et rédaction du rapport
Du 3 au 10 décembre 2020 à 18h UTC : envoi de témoignages sur la réussite du projet et l'expérience de travail avec des mentors
Vous pourrez modifier l'ordre des modules mentionnés ici après une discussion plus poussée avec les mentors.
Comme l'ont suggéré les mentors, je vais d'abord me concentrer sur la mise à jour des modules, qui sont les plus faciles à mettre à jour, avant de passer aux modules plus complexes.
Pourquoi suis-je la personne responsable de ce projet ?
Je pense être la bonne personne pour ce projet, car j'ai une expérience de la rédaction technique en informatique et je maîtrise bien git et github.
J'ai envoyé des demandes d'extraction pour mettre à jour la documentation en fonction du dernier guide de style de sympy, lequel a été fusionné avec succès. Je suis donc confiant dans le flux de travail et j'apporte régulièrement des contributions.
Au début, quand j'ai commencé à contribuer, j'ai rencontré quelques 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'en suis impatient.