Projet AboutCode

Cette page contient les détails d'un projet de rédaction technique accepté pour la Google Season of Docs.

Résumé du projet

Organisation Open Source:
AboutCode
Rédacteur technique:
ayansinha
Nom du projet:
Référence des options de ligne de commande dans scancode-toolkit et réorganisation de la structure de la documentation AboutCode sur aboutcode.readthedocs.io
Durée du projet:
Durée standard (trois mois)

Project description

[ 1. Options de ligne de commande pour Scancode-Toolkit ]

Scancode-Toolkit propose de nombreuses options de ligne de commande pour personnaliser la façon dont l'analyse est effectuée, le format de sortie et plusieurs autres options, comme les plug-ins post-analyse. Actuellement, nous ne disposons pas de la documentation nécessaire pour expliquer ces options. Elles ne sont disponibles que via l'indicateur "--help" ou "-h". Ce projet vise à créer une documentation complète qui explique:

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

  • Objectif: liste exhaustive de toutes les options possibles via la ligne de commande.
  • Présentation de base: tout d'abord, nous abordons les options d'analyse par défaut, avec un exemple de résultat. Brève illustration/description de la façon dont l'analyse est effectuée.
    Par la suite, 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 discutés en détail et contenir 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 options de versions croisées, l'API et les modifications de la documentation.
  • Problème: Actuellement, la documentation du wiki et des pages ReadTheDocs concerne les anciennes versions et doit être restructurée de manière importante.
  • Présentation générale : les parties du kit d'outils de code-barres qui ont été mises à jour/peuvent être mises à jour dans la version sont
  • Options de ligne de commande
  • API
  • Documentation (à lancer) Les options de ligne de commande et les API sont modifiées dans les versions et les versions, et la documentation doit également suivre, sinon les utilisateurs risquent de semer la confusion. L'utilitaire de ligne de commande [ --help ] est déjà mis à jour pour toute modification des options et peut être utilisé pour reproduire la gestion des versions dans la documentation.

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

  • Objectif: Cette section fournit un résumé de base sur la façon dont les résultats de l'analyse de scancode-toolkit peuvent être utilisés dans différentes causes et sur les options de scancode-toolkit qui fournissent cette fonctionnalité.
  • Présentation de base: cette section fournit différents exemples de scénarios d'utilisation et les options recommandées dans ces scénarios.
  • Remarque: Cette partie nécessite une aide importante de la part du mentor en ce qui concerne les informations et les indications concernant différents cas d'utilisation de Scancode-Toolkit.

[ 4. Modifications apportées par ces options à l'analyse et à la sortie

  • Objectif: Cette section fournit un résumé de base sur la façon dont les résultats de l'analyse de scancode-toolkit peuvent être utilisés dans différentes causes, ainsi que sur les outils Aboutcode qui fournissent cette fonctionnalité.
  • Présentation de base: les options modifient le comportement de l'analyse. Un cas par défaut de base sera illustré dans la section principale [ 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 sur la façon dont les résultats de l'analyse de scancode-toolkit peuvent être utilisés dans différentes causes, ainsi que sur les outils Aboutcode qui fournissent cette fonctionnalité.
  • Présentation générale: Scancode-Tool dispose d'indicateurs permettant de spécifier différents formats de sortie dans lesquels les résultats de l'analyse seront générés. Il s'agit de...
    Cette partie
  • expliquer en détail les formats de sortie
  • donner des exemples de formats de sortie ;
  • fournir d'autres liens correspondant au format de sortie et à son utilisation
  • comment les résultats de l'analyse sont stockés dans les fichiers de sortie. Cela fait également référence à la façon dont ces différents formats sont générés, qui sera expliquée dans [ 2. Discussions expliquant la lecture de code

[ 6. Utilisation commerciale des formats de sortie des codes-barres

  • Objectifs: expliquer les cas d'utilisation métier des formats de sortie des codes-barres Dans la liste d'idées GSoD, les formats de sortie des codes-barres sont mentionnés comme une idée de référence. Cette section implémente la même chose.
  • Remarque: Cette partie nécessite une aide importante de la part du mentor en termes d'informations et de références sur les différents cas d'utilisation métier de Scancode-Toolkit.

[ 7. Comment ces résultats sont utilisés par d'autres projets AboutCode pour une analyse plus approfondie ]

  • Objectif: Cette section fournit un résumé de base sur la façon dont les résultats de l'analyse de scancode-toolkit peuvent être utilisés dans différentes causes, ainsi que sur les outils Aboutcode qui fournissent cette fonctionnalité.
  • Présentation de base:
  • Scancode-Workbench Cette partie explique comment visualiser les résultats avec l'application de bureau et fournit des liens vers la documentation de scancode-workbench pour en savoir plus. Si nécessaire, ajoutera la documentation requise à scancode-workbench.
  • Deltacode Méthode d'analyse des résultats de scancode par Deltacode pour déterminer les différences au niveau du fichier entre deux codebases.

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

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

[ 1. Système de gestion des versions ]

In [ 1. Options de ligne de commande du kit d'outils de scancode -> 2. [Initiate Versioning Structure] 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 à chaque version, ce qui risquerait de créer une certaine confusion.

[ 2. Définir des normes et des tests de documentation

La documentation comporte déjà des tests pour spinx-build (qui compile toutes les pages et recherche des erreurs de syntaxe Sphinx tout au long) et pour la vérification des liens (qui 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 de tirage 17) Il a maintenant besoin de plus de vérifications pour l'analyse lint spécifique dans le texte structuré et d'autres normes. Cela pourrait être réalisé avec restructuredtext-lint, mais nécessite plus de recherches et sera effectué dans le cadre de mon projet GSoD.

[ 3. Ajouter une section "Premiers pas" ]

Cette section servira de point de départ aux nouveaux utilisateurs. Elle contiendra une compilation des documents les plus basiques et importants pour commencer à utiliser Aboutcode Projects. Cette section figure dans chaque projet Aboutcode, y compris Scancode-Toolkit, Scancode-Workbench, Deltacode, etc.

[ 4. Restructuration selon les quatre fonctions de document ]

La documentation existante n'est pas explicitement structurée en quatre fonctions de document : tutoriels, guides, références et explications. Je propose de les structurer en conséquence, en ajoutant des informations/explications/conseils si nécessaire. Ce fichier 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 apportées au reste de la documentation.

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

Des informations supplémentaires sur le code/les API pourraient être ajoutées pour le rendre plus convivial pour les développeurs. Il peut y avoir des liens vers [ 2. Discussions expliquant la section "Analyse du code" ci-dessus. Cela permet de relier l'explication du fonctionnement de l'analyse au code qu'elle utilise pour effectuer l'analyse. Comme ces dossiers contiennent différentes parties de scancode-toolkit, leur utilisation individuelle peut être élaborée avec les API, en lien avec la discussion sur le fonctionnement du scancode.

  • [ cluecode : plugins for scanning licenses, copyrights, urls, emails ]
  • [ commoncode : helper classes and functions]
  • [ extractcode : extrait différents formats d'archives ]
  • [ formattedcode : mise en forme de la sortie pour différents formats de fichier de sortie ]
  • [ licensedcode : licence detection code ]
  • [ packagedcode : analyse de différents formats de package ]
  • [ plugincode : classes for the plugins architecture ]
  • [ summarycode : summarizes scan on detected licenses ]
  • [ textcode : handles text parsing ]
  • [ typecode : gère la détermination du type de fichier ]
  • [ scancode : CLI and API to scancode, the core part ]

Cette sous-section contiendra des informations/API détaillées sur ces parties de scancode-toolkit dans des sous-sections correspondantes. Les consignes de développement se trouvent sur une autre page ou dans une autre section comportant des sous-sections plus petites.

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

La page de questions fréquentes actuelle contient des questions auxquelles il est possible de répondre plus efficacement. Elle devrait être structurée en documents distincts sur la façon de procéder, les tutoriels et les documents de référence.

  • Comment fonctionne ScanCode ? Ce problème est référencé dans [ 2. Les discussions expliquant le scan du code seront présentées dans une section entièrement distincte et beaucoup plus détaillée.
  • Comment ajouter des règles de licence pour la détection améliorée ? Ce problème a déjà été abordé dans l'amélioration des guides pratiques existants, où la documentation sera déplacée vers cette section.
  • Comment ajouter une règle de détection de licence ? Cela pourrait être transformé en un autre article de type "Comment faire" séparément et pourrait être développé.
  • Comment commencer à développer des applications ? 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 nouvelle version Cette section peut être transformée en article distinct intitulé "Créer une nouvelle version".
  • Découvrez d'autres questions fréquentes qui répondent à des questions génériques sur le projet et ne relèvent pas des catégories "Guide"/"Tutoriel".