Esta página contiene los detalles de un proyecto de redacción técnica aceptado para la GDOC Season of Docs.
Resumen del proyecto
- Organización de código abierto:
- AboutCode
- Escritor técnico:
- ayansinha
- Nombre del proyecto:
- Consulta la referencia de las opciones de línea de comandos en scancode-toolkit y reorganiza la estructura de la documentación de AboutCode en aboutcode.readthedocs.io
- Duración del proyecto:
- Duración estándar (3 meses)
Project description
[ 1. Opciones de línea de comandos de Scancode-Toolkit ]
Scancode-Toolkit tiene una gran cantidad de opciones de línea de comandos para personalizar cómo se realiza el análisis, el formato de salida y varias otras opciones, como los complementos posteriores al análisis. Estas opciones actualmente no tienen documentación adecuada para explicarlas y solo están disponibles a través de las marcas “--help” o “-h”. El objetivo de este proyecto es elaborar documentación completa que explique lo siguiente:
[ 1. Todas las opciones disponibles a través de la línea de comandos ]
- Objetivo: Una lista exhaustiva de todas las opciones posibles a través de la línea de comandos.
- Descripción general básica: En primer lugar, se analizan las opciones de análisis predeterminadas, con un ejemplo del resultado. Un gráfico o una descripción breve sobre cómo se realiza el análisis.
A partir de ahora, este comportamiento predeterminado actúa como referencia para ver cómo las otras opciones cambian el análisis y el resultado.
Se analizarán en detalle y contendrán la siguiente información, como se menciona en las siguientes secciones.
[ 2. Inicia la estructura del control de versiones ]
- Objetivo: Iniciar un sistema de control de versiones para mantener correctamente los cambios de documentación y API/opciones de versiones cruzadas.
- Problema: Actualmente, la documentación de la wiki y las páginas de ReadTheDocs son para versiones anteriores y necesitan una reestructuración importante.
- Descripción general básica: Las partes del kit de herramientas de scancode que se actualizaron o podrían actualizarse en la versión son las siguientes:
- Opciones de línea de comandos
- API
- Documentación (por iniciar) Las opciones de la línea de comandos y las APIs se cambian en las versiones y actualizaciones, y también se debe seguir la documentación, o crearán una gran confusión para los usuarios. La utilidad de línea de comandos [ --help ] ya se actualizó para cualquier cambio en las opciones y se podría usar para replicar el control de versiones en la documentación.
[ 3. Cómo se pueden usar estas opciones en diferentes casos ]
- Objetivo: En esta sección, se proporcionará un resumen básico de cómo se pueden usar los resultados de la búsqueda de scancode-toolkit en diferentes causas y las opciones de Scancode-Toolkit que proporcionan esa funcionalidad.
- Descripción general básica: En esta sección, se proporcionan diferentes ejemplos de situaciones de casos de uso y las opciones que se recomiendan en esas situaciones.
- Nota: Esta parte requiere una gran ayuda del mentor en términos de entradas sobre varios casos de uso de Scancode-Toolkit y punteros a ellos.
[ 4. Qué cambian estas opciones en el análisis y la salida
- Objetivo: En esta sección, se proporcionará un resumen básico de cómo se pueden usar los resultados del análisis de scancode-toolkit en diferentes causas y las herramientas de Aboutcode que proporcionan esa funcionalidad.
- Descripción general básica: Las opciones cambian el comportamiento de cómo se realiza el análisis. En la sección principal, se ilustrará un caso predeterminado básico [ 1. Todas las opciones disponibles a través de la línea de comandos ] y esta sección compararán los cambios que todas las opciones aportan a esta situación predeterminada.
[ 5. Formatos de salida y sus ejemplos ]
- Objetivo: Esta sección proporcionará un resumen básico de cómo se pueden usar los resultados del análisis de scancode-toolkit en diferentes causas y las herramientas de Aboutcode que proporcionan esa funcionalidad.
- Descripción general básica: Scancode-Tool tiene marcas para especificar diferentes formatos de salida en los que se generarán los resultados del análisis. Estos son: -
Esta parte - explica en detalle los formatos de salida
- dar ejemplos de los formatos de salida
- proporcionar otros vínculos correspondientes al formato de salida y su uso
- cómo se almacenan los resultados de la búsqueda en los archivos de salida. También incluye un vínculo a Cómo se generan estos diferentes formatos, que se explicará en [ 2. Debates que explican el escaneo de código ].
[ 6. Uso comercial de formatos de salida de códigos de barras ]
- Objetivos: Explicar los casos de uso empresariales de los formatos de salida de Scancode En la lista de ideas de GSoD, se mencionan los formatos de salida de Scancode como idea de referencia. En esta sección, se implementa lo mismo.
- Nota: Esta parte requiere una ayuda significativa del mentor en términos de entradas sobre varios casos de uso empresariales de Scancode-Toolkit y punteros a ellos.
[ 7. Cómo otros proyectos de AboutCode usan estos resultados para realizar un análisis más detallado ]
- Objetivo: Esta sección proporcionará un resumen básico de cómo se pueden usar los resultados del análisis de scancode-toolkit en diferentes causas y las herramientas de Aboutcode que proporcionan esa funcionalidad.
- Descripción general básica:
- Scancode-Workbench En esta parte, se explica la visualización de resultados con la app de escritorio y punteros a la documentación de Scancode-Workbench para obtener más asistencia. Se agregará la documentación requerida a Scancode-Workbench si es necesario.
- Deltacode Cómo Deltacode toma los resultados del código de escaneo para determinar las diferencias a nivel de archivo entre dos bases de código.
[ 2. Reorganizar la estructura de la documentación de AboutCode ]
Esta parte incluye una gran cantidad de cambios en la documentación de Aboutcode.
[ 1. Sistema de control de versiones ]
En [ 1. Opciones de línea de comandos de Scancode-Toolkit -> 2. Inicia la estructura de control de versiones] se menciona el problema de control de versiones de las opciones de la línea de comandos. Lo mismo es necesario para otras partes de la documentación que contienen comandos o información específicos de la versión que, de otro modo, crearían confusión.
[ 2. Configuración de estándares y pruebas de documentación ]
La documentación ya tiene pruebas para spinx-build (compila todas las páginas y comprueba en busca de errores de sintaxis de Sphinx en general) y verificación de vínculos (comprueba todos los vínculos a otras páginas web de la documentación) con integración continua a través de Travis-CI. (Agregada por mí en esta solicitud de extracción n.o 17) Ahora necesita más comprobaciones para el análisis con lint específico de texto reestructurado y otros estándares. Esto se podría lograr con restructuredtext-lint, pero se necesita más investigación y se hará como parte de mi proyecto de GSoD.
[ 3. Agrega una sección de “Introducción” ]
Esta sección servirá como punto de partida para los recién llegados y contendrá una compilación de los documentos más básicos e importantes para comenzar a usar los proyectos de Aboutcode. Todos los proyectos de Aboutcode tendrán esta sección que incluye Scancode-Toolkit, Scancode-Workbench y Deltacode, entre otras.
[ 4. Reestructuración según las 4 funciones del documento ]
La documentación existente no está estructurada de forma explícita en las 4 funciones de documentos: instructivos, instructivos, referencias y explicaciones. Te propongo estructurarlos según corresponda y agregar más información, explicaciones o indicadores según sea necesario. Esto se aplica a todos los proyectos de AboutCode y su documentación. A continuación, se muestran dos ejemplos de la reestructuración de la documentación de Scancode-Toolkit que propongo y me gustaría continuar en este proyecto. Se llevarán a cabo cambios similares en el resto de la documentación.
[ 5. Reestructuración de la página de desarrollo (Scancode-Toolkit)
Se podría agregar más información sobre el código o las APIs para que sea más fácil para los desarrolladores. Puede haber vínculos a [ 2. Debates en los que se explica la sección anterior de Escaneo de código Esto vincula la explicación de cómo funciona el análisis con el código que usa para realizarlo. Como estas carpetas contienen diferentes partes de scancode-toolkit, su uso individual se puede desarrollar con las APIs, junto con la discusión sobre cómo funciona el código de escaneo.
- [ cluecode : plugins for scanning licenses, copyrights, urls, emails ]
- [commoncode : clases y funciones auxiliares]
- [ extractcode : extracts different archive formats ]
- [ formattedcode : output formatting for different output file formats ]
- [ licensedcode : licence detection code ]
- [ packagedcode : parsing various package formats ]
- [ plugincode : classes for the plugins architecture ]
- [ summarycode : summarizes scan on detected licenses ]
- [ textcode : handles text parsing ]
- [ typecode : controla las determinaciones del tipo de archivo ]
- [ scancode : CLI and API to scancode, the core part ]
Esta subsección contendrá información o APIs detalladas sobre estas partes de scancode-toolkit en subsecciones según corresponda. Las pautas de desarrollo estarán en otra página o en otra sección con subsecciones más pequeñas.
[ 6. Reestructuración de la página de preguntas frecuentes (Scancode-Toolkit)
Actualmente, la página de Preguntas frecuentes tiene preguntas que se pueden responder mejor y debe estructurarse como instructivos, instructivos y documentos de referencia separados.
- ¿Cómo funciona ScanCode? Este problema se menciona en [ 2. Los debates en los que se explica el escaneo de código ] serán una sección completamente separada con muchos más detalles.
- ¿Cómo agregar nuevas reglas de licencias para la detección mejorada? Este problema ya se analizó en Mejorar los instructivos existentes, y la documentación se trasladará allí.
- ¿Cómo agregar una nueva regla de detección de licencias? Esto se podría convertir en otra entrada de instructivo por separado y se podría explicar con más detalle.
- ¿Cómo comenzar a desarrollar? Ya hay una página de desarrollo independiente y la información se superpone bastante. Ya se analizó la reestructuración de la página de desarrollo.
- Pasos para cortar un nuevo lanzamiento Esto se puede transformar en un instructivo aparte “How To Cut a new release”.
- Encuentra más preguntas frecuentes que responden a preguntas genéricas sobre el proyecto y que no pertenecen a las categorías “Instructivos”/“Instructivos”.