Projet AboutCode

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:
AboutCode
Rédacteur technique:
ayansinha
Nom du projet:
Référence pour les options de ligne de commande dans scancode-kit et réorganisation de la structure de la documentation AboutCode sur aboutcode.readthedocs.io
Durée du projet:
Durée standard (3 mois)

Project description

[ 1. Options de ligne de commande Scancode-Toolkit

Scancode-Toolkit dispose de nombreuses options de ligne de commande permettant de personnaliser la façon dont l'analyse est effectuée, le format de sortie et plusieurs autres options, telles que des plug-ins post-analyse. Ces options ne disposent actuellement pas de documentation appropriée pour les expliquer et ne sont disponibles que via l'indicateur "--help" ou "-h". Ce projet vise à élaborer une documentation complète qui explique:

[ 1. Toutes les options disponibles via la ligne de commande ]

  • Objectif: obtenir une liste exhaustive de toutes les options disponibles via la ligne de commande.
  • Présentation de base: Tout d'abord, les options d'analyse par défaut sont abordées, avec un exemple de résultat. Bref graphique/description du mode de numérisation.
    Ci-dessous, ce comportement par défaut sert de référence à la façon dont les autres options modifient l'analyse et la sortie.
    Ces éléments doivent être abordés en détail et contiennent les informations suivantes, comme indiqué dans les sections suivantes.

[ 2. Lancer la structure de gestion des versions ]

  • Objectif: lancer un système de gestion des versions afin de gérer correctement les modifications des options/de l'API et de la documentation entre les versions.
  • Problème: actuellement, la documentation du wiki et les pages ReadTheDocs concernent des versions plus anciennes et nécessitent une restructuration importante.
  • Présentation de base : Les parties du kit d'outils scancode qui ont été mises à jour ou qui pourraient être mises à jour dans la version sont
  • Options de ligne de commande
  • API
  • Documentation (à démarrer) Les options de ligne de commande et les API sont modifiées dans les versions et les versions. La documentation doit également respecter les règles, sans quoi cela créera une grande confusion pour les utilisateurs. L'utilitaire de ligne de commande [ --help ] est déjà mis à jour en cas de modification des options et peut être utilisé pour répliquer la gestion des versions dans la documentation.

[ 3. Comment utiliser ces options dans différents cas ? ]

  • Objectif: cette section fournira un résumé de base de la manière dont les résultats d'analyse de Scancode-Toolkit peuvent être utilisés dans différentes causes, ainsi que les options du Scancode-Toolkit qui proposent cette fonctionnalité.
  • Présentation de base: cette section fournit différents exemples de scénarios d'utilisation et les options recommandées.
  • Remarque: Cette partie nécessite une aide considérable de la part du mentor.

[ 4. Ce que ces options changent dans l'analyse et la sortie ]

  • Objectif: cette section fournit un résumé de base de la façon dont les résultats d'analyse de Scancode-Toolkit peuvent être utilisés pour différentes causes, ainsi que les outils Aboutcode qui proposent ces fonctionnalités.
  • Présentation de base: les options modifient le comportement de l'analyse. Un cas basique par défaut sera illustré dans la section initiale [ 1. Toutes les options disponibles via la ligne de commande ] et cette section compare les modifications apportées par toutes les options à ce scénario par défaut.

[ 5. Formats de sortie et exemples ]

  • Objectif: cette section fournit un résumé de base de la façon dont les résultats d'analyse de Scancode-Toolkit peuvent être utilisés pour différentes causes, ainsi que les outils Aboutcode qui proposent ces fonctionnalités.
  • Présentation de base: Scancode-Tool comporte des indicateurs permettant de spécifier les différents formats de sortie dans lesquels les résultats d'analyse seront générés. Il s'agit...
    Cette partie
  • expliquer en détail les formats de sortie
  • donner des exemples de formats de sortie
  • donne d'autres liens correspondant au format de sortie et à son utilisation
  • la manière dont les résultats d'analyse sont stockés dans les fichiers de sortie. Cela renvoie également à la façon dont ces différents formats sont générés, qui est expliquée dans [ 2. Discussions expliquant la numérisation de code ].

[ 6. Utilisation commerciale des formats de sortie Scancode ]

  • Objectifs: expliquer les cas d'utilisation commerciale des formats de sortie Scancode Dans la liste des idées GSoD, Scancode Output Formats est cité en tant qu'idée de référence. Dans cette section, le processus est identique.
  • Remarque : Cette partie nécessite une aide considérable de la part du mentor : il fournit des informations sur divers cas d'utilisation de Scancode-Toolkit et des indications vers différents cas d'utilisation en entreprise.

[ 7. Comment ces résultats sont utilisés par d'autres projets AboutCode à des fins d'analyse plus poussée ]

  • Objectif: cette section fournit un résumé de base de la façon dont les résultats d'analyse de Scancode-Toolkit peuvent être utilisés pour différentes causes, ainsi que les outils Aboutcode qui proposent ces fonctionnalités.
  • Présentation générale:
  • Scancode-Workbench Cette partie explique comment visualiser les résultats à l'aide de l'application de bureau et fournit des pointeurs vers la documentation de scancode-workbench pour bénéficier d'une assistance supplémentaire. Ajoute la documentation requise à scancode-workbench si nécessaire.
  • Deltacode Comment les résultats du scancode sont analysés par Deltacode pour déterminer les différences au niveau des fichiers entre deux codebases.

[ 2. Réorganisez la structure de la documentation AboutCode ]

Cette partie inclut de nombreuses modifications apportées à la documentation Aboutcode

[ 1. Système de gestion des versions ]

Dans [ 1. Options de ligne de commande Scancode-Toolkit -> 2. Lancer la structure de gestion des versions] le problème de gestion des versions des options de ligne de commande est mentionné. Il en va de même pour d'autres parties de la documentation qui contiennent des commandes ou des informations spécifiques aux versions, qui seraient autrement source de confusion.

[ 2. Définir les normes et les tests de documentation ]

La documentation comporte déjà des tests pour "spinx-build" (crée toutes les pages et recherche les erreurs de syntaxe Sphinx) et la vérification des liens (vérifie tous les liens vers d'autres pages Web de la documentation) avec l'intégration continue via Travis-CI. (Ajouté par moi dans cette demande d'extraction n° 17) Désormais, des vérifications d'analyse lint spécifiques sont nécessaires dans le texte restructuré et dans d'autres normes. Cela peut être réalisé avec la fonctionnalité restructurée-lint, mais nécessite plus de recherches et sera effectuée dans le cadre de mon projet GSoD.

[ 3. Ajout d'une section "Premiers pas" ]

Il servira de section de départ pour les débutants et contiendra une compilation des documents les plus élémentaires et les plus importants pour commencer à utiliser les projets Aboutcode. Tous les projets Aboutcode comportent cette section, y compris Scancode-Toolkit, Scancode-Workbench, Deltacode et d'autres.

[ 4. Restructurer selon les quatre fonctions de document ]

La documentation existante n'est pas explicitement structurée dans les 4 fonctions du document : Tutoriels, Tutoriels, Références et Explications. Je propose de les structurer en conséquence, en y ajoutant autant d'informations/d'explications/de pointeurs que nécessaire. Ce nom s'applique à tous les projets AboutCode et à leur documentation. Vous trouverez ci-dessous deux exemples de restructuration de la documentation Scancode-Toolkit que je propose et que je souhaite poursuivre dans ce projet. Des modifications similaires seront effectuées pour le reste de la documentation.

[ 5. Restructurer la page de développement (Scancode-Toolkit) ]

Des informations supplémentaires sur le code et les API pourraient être ajoutées afin de faciliter la tâche des développeurs. Il peut y avoir des liens vers le [ 2. Discussions expliquant la section "Numérisation de code" ci-dessus. L'explication du fonctionnement de l'analyse est ainsi liée au code qu'elle utilise pour effectuer l'analyse. Comme ces dossiers contiennent différentes parties de scancode-Tool, leur utilisation individuelle peut être élaborée à l'aide des API, en lien avec la discussion sur le fonctionnement de scancode.

  • [ code d'indice : plug-ins permettant d'analyser les licences, droits d'auteur, URL, e-mails ]
  • [ commoncode : classes et fonctions d'assistance]
  • [ extractcode : extrait différents formats d'archive ]
  • [ formattedcode : format de sortie pour différents formats de fichiers de sortie ]
  • [licensecode : code de détection de licence ]
  • [ packagedcode : analyse de différents formats de packages ]
  • [ plugincode : classes pour l'architecture des plugins ]
  • [ summarycode : récapitule l'analyse des licences détectées ]
  • [ textcode : gère l'analyse du texte ]
  • [ typecode : gère la détermination du type de fichier ]
  • [ scancode : CLI et API pour scanner du code, la partie essentielle ]

Cette sous-section contiendra des informations/API détaillées sur ces parties de Scancode-Toolkit dans les autres sous-sections. Vous y trouverez les consignes de développement sur une autre page ou une autre section comportant des sous-sections plus petites.

[ 6. Restructuration de la page des questions fréquentes (Scancode-Toolkit) ]

À l'heure actuelle, la page des questions fréquentes contient des questions auxquelles il est possible de répondre. Elle doit être structurée séparément (instructions, tutoriels et documents de référence).

  • Comment fonctionne ScanCode ? Ce problème est référencé dans [ 2. Les discussions expliquant la numérisation de code ] feront l'objet d'une section entièrement distincte.
  • Ajouter de nouvelles règles de licence pour la détection améliorée ? Ce problème a déjà été abordé dans la section "Améliorer les tutoriels existants". La documentation y sera déplacée.
  • Comment ajouter une nouvelle règle de détection des licences ? Cela pourrait être rédigé dans un autre article de type "Comment faire" et pourrait être développé plus en détail.
  • Premiers pas avec le développement Il existe déjà une page de développement distincte et les informations se chevauchent beaucoup. La restructuration de la page de développement a déjà été abordée ci-dessus.
  • Étapes à suivre pour créer une sortie Cette vidéo peut être transformée en une section "Comment créer une nouvelle version" distincte.
  • Trouvez d'autres questions fréquentes qui répondent à des questions génériques sur le projet et qui ne figurent pas dans les catégories "Tutoriels" et "Tutoriels".