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 :
- Reference for Command Line Options in scancode-toolkit and Reorganize the structure of AboutCode documentation at aboutcode.readthedocs.io
- Durée du projet :
- Durée standard (3 mois)
Description du projet
[ 1. Options de ligne de commande de Scancode-Toolkit ]
Scancode-Toolkit propose de nombreuses options de ligne de commande pour personnaliser l'exécution de l'analyse, le format de sortie et plusieurs autres options, comme les plug-ins post-analyse. Ces options ne disposent actuellement pas d'une documentation appropriée pour les expliquer et 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 : une 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 sortie. Un bref graphique/une brève description expliquent comment l'analyse est effectuée.
Ce comportement par défaut sert ensuite de référence pour montrer comment les autres options modifient l'analyse et la sortie.
Ces options seront abordées en détail et contiendront les informations suivantes, comme indiqué dans les sections suivantes.
[ 2. Lancement de la structure de gestion des versions ]
- Objectif : lancer un système de gestion des versions pour assurer la maintenance appropriée des options/API et des modifications de la documentation entre les versions.
- Problème : actuellement, la documentation des pages wiki et ReadTheDocs concerne d'anciennes versions et nécessite une restructuration majeure.
- Présentation de base : les parties de scancode-toolkit qui ont été mises à jour/pourraient être mises à jour dans la version sont les suivantes :
- 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 releases, et la documentation doit également suivre ces modifications, sinon les utilisateurs seront très confus. L'utilitaire de ligne de commande [ --help ] est déjà mis à jour pour toutes les modifications apportées aux options et peut être utilisé pour répliquer la gestion des versions dans la documentation.
[ 3. Comment ces options peuvent être utilisées dans différents cas ]
- Objectif : cette section fournit un résumé de base de la manière dont les résultats d'analyse de scancode-toolkit peuvent être utilisés dans différents cas et des options de Scancode-Toolkit qui offrent cette fonctionnalité.
- Présentation de base : cette section présente 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 du mentor en termes d'entrées et de pointeurs vers différents cas d'utilisation de Scancode-Toolkit.
[ 4. Ce que ces options modifient dans l'analyse et la sortie ]
- Objectif : cette section fournit un résumé de base de la manière dont les résultats d'analyse de scancode-toolkit peuvent être utilisés dans différents cas et des outils Aboutcode qui offrent 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 comparera les modifications que toutes les options apportent à ce scénario par défaut.
[ 5. Formats de sortie et leurs exemples ]
- Objectif : cette section fournit un résumé de base de la manière dont les résultats d'analyse de scancode-toolkit peuvent être utilisés dans différents cas et des outils Aboutcode qui offrent cette fonctionnalité.
- Présentation de base : Scancode-Tool comporte des indicateurs permettant de spécifier différents formats de sortie dans lesquels les résultats d'analyse seront générés. Ces indicateurs sont les suivants :
Cette partie - explique en détail les formats de sortie ;
- donne des exemples de formats de sortie ;
- fournit d'autres liens correspondant au format de sortie et à son utilisation ;
- explique comment les résultats d'analyse sont stockés dans les fichiers de sortie. Elle renvoie également à la section expliquant comment ces différents formats sont générés, qui sera abordée dans [ 2. Discussions expliquant l'analyse de code ].
[ 6. Utilisation professionnelle des formats de sortie de Scancode ]
- Objectifs : expliquer les cas d'utilisation professionnelle des formats de sortie de Scancode Dans la liste d'idées GSoD, les formats de sortie de Scancode sont mentionnés comme idée de référence. Cette section met en œuvre cette idée.
- Remarque : cette partie nécessite une aide importante du mentor en termes d'entrées et de pointeurs vers différents cas d'utilisation professionnelle de Scancode-Toolkit.
[ 7. Comment ces sorties sont utilisées par d'autres projets AboutCode pour une analyse plus approfondie ]
- Objectif : cette section fournit un résumé de base de la manière dont les résultats d'analyse de scancode-toolkit peuvent être utilisés dans différents cas et des outils Aboutcode qui offrent cette fonctionnalité.
- Présentation de base :
- Scancode-Workbench : cette partie explique comment visualiser les résultats avec l'application de bureau et fournit des pointeurs vers la documentation de scancode-workbench pour obtenir plus d'aide à ce sujet. Ajoutera la documentation requise à scancode-workbench si nécessaire.
- Deltacode : comment les résultats de scancode sont utilisés par Deltacode pour déterminer les différences au niveau des fichiers entre deux bases de code.
[ 2. Restructuration de la documentation AboutCode ]
Cette partie inclut un certain nombre de modifications apportées à la documentation Aboutcode.
[ 1. Système de gestion des versions ]
Dans [ 1. Options de ligne de commande de Scancode-Toolkit -> 2. Lancement de la structure de gestion des versions ], le problème de la gestion des versions des options de ligne de commande est mentionné. Il est également nécessaire pour d'autres parties de la documentation qui contiennent des commandes/informations spécifiques à une version et qui pourraient sinon créer une confusion.
[ 2. Définition des normes et des tests de documentation ]
La documentation comporte déjà des tests pour spinx-build (qui compile toutes les pages et vérifie les erreurs de syntaxe Sphinx) et pour la vérification des liens (qui vérifie tous les liens vers d'autres pages Web à partir de la documentation) avec l'intégration continue via Travis-CI. (Ajouté par moi dans cette requête d'extraction n° 17) Elle nécessite désormais davantage de vérifications pour la validation spécifique dans reStructured Text et d'autres normes. Cela peut être réalisé avec restructuredtext-lint, mais nécessite davantage de recherches et sera effectué dans le cadre de mon projet GSoD.
[ 3. Ajout d'une section "Premiers pas" ]
Cette section servira de point de départ pour les nouveaux utilisateurs et contiendra une compilation des documents les plus basiques et les plus importants pour commencer à utiliser les projets Aboutcode. Chaque projet Aboutcode disposera de cette section, y compris Scancode-Toolkit, Scancode-Workbench, Deltacode, etc.
[ 4. Restructuration en fonction des quatre fonctions de document ]
La documentation existante n'est pas explicitement structurée en fonction des quatre fonctions de document : tutoriels, guides pratiques, référence et explications. Je propose de les structurer en conséquence, en ajoutant des informations/explications/pointeurs si nécessaire. Cela vaut pour 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 j'aimerais réaliser dans ce projet. Des modifications similaires seront apportées au reste de la documentation.
[ 5. Restructuration de la page de développement (Scancode-Toolkit) ]
Il est possible d'ajouter plus d'informations sur le code/les API pour le rendre plus convivial pour les développeurs. Il peut y avoir des liens vers la section [ 2. Discussions expliquant l'analyse de code ] ci-dessus. Cela permet de lier 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 détaillée avec les API, en complément de la discussion sur le fonctionnement de scancode.
- [ cluecode : plug-ins pour l'analyse des licences, des droits d'auteur, des URL et des 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 ]
- [ licensedcode : 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 de texte ]
- [ typecode : gère la détermination du type de fichier ]
- [ scancode : CLI et API pour scancode, la partie principale ]
Cette sous-section contiendra des informations/API détaillées sur ces parties de scancode-toolkit dans des sous-sous-sections. Les consignes de développement se trouveront 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 contient actuellement des questions auxquelles il est possible de répondre plus précisément et qui devraient être structurées séparément sous forme de guides pratiques, de tutoriels et de documents de référence.
- Comment fonctionne ScanCode ? Ce problème est référencé dans [ 2. Discussions expliquant l'analyse de code ] et fera l'objet d'une section entièrement distincte beaucoup plus détaillée.
- Comment ajouter de nouvelles règles de licence pour améliorer la détection ? Ce problème a déjà été abordé dans Amélioration des guides pratiques existants. La documentation sera déplacée vers cette section.
- Comment ajouter une nouvelle règle de détection de licence ? Cela pourrait faire l'objet d'un autre article "Guide pratique" distinct et être développé.
- Comment commencer à développer ? 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 un guide pratique distinct intitulé "Créer une nouvelle version".
- Trouvez d'autres questions fréquentes qui répondent à des questions génériques sur le projet et qui ne relèvent pas des catégories "Guide pratique"/"Tutoriel".