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 sur les 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 (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 les 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 à produire une documentation complète expliquant:

[ 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, les options d'analyse par défaut sont abordées, avec un exemple de résultat. Brève description graphique/description de la façon dont l'analyse est effectuée.
    Ci-après, 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 options pour toutes les versions, ainsi que les modifications d'API et de documentation
  • Problème: actuellement, la documentation du wiki et les pages ReadTheDocs concernent des versions antérieures et nécessitent une restructuration importante.
  • Présentation de base : Les parties de scancode-Toolkit qui ont été mises à jour/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, sans quoi cela créerait une grande confusion pour les utilisateurs. L'utilitaire de ligne de commande [ --help ] est déjà mis à jour pour prendre en compte toute modification des options et pourrait être utilisé pour répliquer la gestion des versions dans la documentation.

[ 3. Utilisation de ces options dans différents cas ]

  • Objectif: cette section fournira un résumé sommaire de l'utilisation des résultats de scancode-Toolkit pour différentes causes, ainsi que les options du Scancode-Toolkit qui offrent cette fonctionnalité.
  • Présentation de base: cette section présente différents exemples de cas d'utilisation et indique les options recommandées.
  • Remarque: Cette partie nécessite une aide considérable de la part du mentor.

[ 4. Changements de ces options dans l'analyse et la sortie ]

  • Objectif: cette section fournira un résumé général de la façon dont les résultats d'analyse de scancode-Tool peuvent être utilisés pour différentes causes, et les outils Aboutcode qui offrent cette fonctionnalité.
  • Vue d'ensemble de base: les options modifient le comportement de l'analyse. Un cas de base par défaut est illustré dans la section initiale [ 1. Toutes les options disponibles via la ligne de commande ] et cette section compare les modifications que toutes les options apportent à ce scénario par défaut.

[ 5. Formats de sortie et exemples ]

  • Objectif: cette section fournira un résumé général de la façon dont les résultats d'analyse de scancode-Tool peuvent être utilisés pour différentes causes, et les outils Aboutcode qui offrent cette fonctionnalité.
  • Présentation de base: Scancode-Tool dispose d'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 de...
    Cette partie
  • expliquent en détail les formats de sortie
  • donner des exemples sur les formats de sortie
  • d'autres liens correspondant au format de sortie et à son utilisation
  • le stockage des résultats d'analyse dans les fichiers de sortie. Cette section contient également un lien vers la façon dont ces différents formats sont générés, qui est expliqué dans [ 2. Discussions expliquant le scan de code ].

[ 6. Utilisation commerciale des formats de sortie Scancode ]

  • Objectifs: expliquer les cas d'utilisation métier des formats de sortie Scancode Dans la liste des idées GSoD, les formats de sortie Scancode sont mentionnés comme une idée de référence. Cette section met en œuvre la même implémentation.
  • Remarque: Cette partie nécessite une aide considérable de la part du mentor.

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

  • Objectif: cette section fournira un résumé général de la façon dont les résultats d'analyse de scancode-Tool peuvent être utilisés pour différentes causes, et les outils Aboutcode qui offrent cette fonctionnalité.
  • Présentation générale:
  • Scancode-Workbench Cette partie explique comment visualiser les résultats avec l'application de bureau et les 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 Deltacode utilise les résultats scancode pour déterminer les différences de niveau de fichier entre deux codebases.

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

Cette partie comprend 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 à la version qui, autrement, créeraient une 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 vérifie 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 lint supplémentaires sont nécessaires dans le texte restructuré et d'autres normes. Cela pourrait être obtenu avec restructurétext-lint, mais cela nécessite plus de recherches et sera fait 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 disposeront de cette section, y compris Scancode-Toolkit, Scancode-Workbench, Deltacode et bien d'autres.

[ 4. Restructuration selon les quatre fonctions de document ]

La documentation existante n'est pas explicitement structurée dans les quatre fonctions du document : Tutoriels, Tutoriels, Référence et Explications. Je propose de les structurer en conséquence, en ajoutant plus d'informations/d'explications/de pointeurs, si nécessaire. Cela concerne tous les projets AboutCode et leur documentation. Vous trouverez ci-dessous deux exemples de restructuration de la documentation du 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 et les API pourraient être ajoutées pour faciliter la tâche des développeurs. Il peut contenir des liens vers [ 2. Discussions expliquant la section "Scanner de code" ] ci-dessus. L'explication du fonctionnement de l'analyse sera ainsi associée au code utilisé pour effectuer l'analyse. Comme ces dossiers contiennent différentes parties de scancode-Tool, leur utilisation individuelle peut être développée avec les API, en lien avec la discussion sur le fonctionnement de scancode.

  • [ indicateur : plug-ins permettant d'analyser les licences, droits d'auteur, URL, adresses e-mail ]
  • [commoncode : classes et fonctions d'assistance]
  • [ extractcode : extrait différents formats d'archive ]
  • [ formattedcode : format de sortie pour différents formats de fichier de sortie ]
  • [licensecode : code de détection de licence ]
  • [ packagedcode : analyse de différents formats de packages ]
  • [ plugincode : classes pour l'architecture des plug-ins ]
  • [ summarycode : résume 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 permettant de scanner du code, la partie principale ]

Cette sous-section contiendra des informations et des API détaillées sur ces parties de scancode-Toolkit. Les consignes de développement figureront 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 trouver des réponses plus pertinentes. 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é à l'étape [ 2. Les discussions expliquant le scan de code ] constituent une section entièrement distincte.
  • Comment ajouter de nouvelles règles de licence pour améliorer la détection ? Ce problème a déjà été abordé dans la section "Améliorer les guides pratiques existants". La documentation y sera déplacée.
  • Comment ajouter une nouvelle règle de détection des licences ? Cela pourrait faire l'objet d'un autre post de type "Comment faire" et donner plus de détails à ce sujet.
  • Comment vous lancer dans le développement ? Il existe déjà une page de développement distincte, et les informations se chevauchent fortement. Nous avons déjà abordé la restructuration de la page de développement ci-dessus.
  • Étapes à suivre pour créer un nouveau titre Cette vidéo peut être transformée en un "How To Cut a new release" distinct.
  • Vous trouverez d'autres questions fréquentes qui répondent à des questions d'ordre général sur le projet et qui n'entrent pas dans les catégories « Comment faire »/« Tutoriel ».