En esta página, se incluyen los detalles de un proyecto de redacción técnica aceptado para el Google Season of Docs.
Resumen del proyecto
- Organización de código abierto:
- AboutCode
- Redactor técnico:
- ayansinha
- Nombre del proyecto:
- Reference for Command Line Options in scancode-toolkit and Reorganize the structure of AboutCode documentation at aboutcode.readthedocs.io
- Duración del proyecto:
- Duración estándar (3 meses)
Descripción del proyecto
[ 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 la forma en que se realiza el análisis, el formato de salida y varias otras opciones, como los complementos posteriores al análisis. Actualmente, estas opciones no tienen la documentación adecuada para explicarlas y solo están disponibles a través de la marca “--help” o “-h”. El objetivo de este proyecto es crear 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: Primero, se analizan las opciones de análisis predeterminadas, con un ejemplo del resultado. Un breve gráfico o descripción sobre cómo se realiza el análisis.
A partir de aquí, este comportamiento predeterminado actúa como referencia para la forma en que las otras opciones cambian el análisis y el resultado.
Estos se analizarán en detalle y contendrán la siguiente información, como se menciona en las siguientes secciones.
[ 2. Cómo iniciar la estructura de control de versiones ]
- Objetivo: Iniciar un sistema de control de versiones para mantener correctamente las opciones, la API y los cambios en la documentación de las diferentes versiones.
- 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
- APIs
- Documentación (para iniciar) Las opciones de línea de comandos y las APIs cambian en las versiones y los lanzamientos, y la documentación también debe seguir el mismo proceso, o creará una gran confusión para los usuarios. La utilidad de línea de comandos [ --help ] ya está actualizada para cualquier cambio en las opciones y se puede 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 del análisis del kit de herramientas de scancode en diferentes causas y las opciones del kit de herramientas de scancode que proporcionan esa funcionalidad.
- Descripción general básica: En esta sección, se proporcionan diferentes ejemplos de casos de uso y qué opciones se recomiendan en esos casos.
- Nota: Esta parte requiere una ayuda significativa del mentor en términos de entradas sobre y punteros a varios casos de uso del kit de herramientas de scancode.
[ 4. Qué cambian estas opciones en el análisis y el resultado ]
- Objetivo: En esta sección, se proporcionará un resumen básico de cómo se pueden usar los resultados del análisis del kit de herramientas de scancode en diferentes causas y las herramientas de Aboutcode que proporcionan esa funcionalidad.
- Descripción general básica: Las opciones cambian el comportamiento de la forma en que se realiza el análisis. Se ilustrará un caso predeterminado básico en la sección principal [ 1. Todas las opciones disponibles a través de la línea de comandos ], y esta sección comparará los cambios que todas las opciones aportan a este caso predeterminado.
[ 5. Formatos de salida y sus ejemplos ]
- Objetivo: En esta sección, se proporcionará un resumen básico de cómo se pueden usar los resultados del análisis del kit de herramientas de scancode 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 los siguientes:
Esta parte - explicará en detalle los formatos de salida
- proporcionará ejemplos de los formatos de salida
- proporcionará otros vínculos correspondientes al formato de salida y su uso
- cómo se almacenan los resultados del análisis en los archivos de salida. También se vincula a Cómo se generan estos diferentes formatos, que se explicará en [ 2. Explicaciones sobre el análisis de código ].
[ 6. Uso empresarial de los formatos de salida de Scancode ]
- Objetivos: Explicar los casos de uso empresarial de los formatos de salida de Scancode En la lista de ideas de GSoD, los formatos de salida de Scancode se mencionan como una 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 y punteros a varios casos de uso empresarial del kit de herramientas de scancode.
[ 7. Cómo usan estos resultados otros proyectos de AboutCode para realizar más análisis ]
- Objetivo: En esta sección, se proporcionará un resumen básico de cómo se pueden usar los resultados del análisis del kit de herramientas de scancode en diferentes causas y las herramientas de Aboutcode que proporcionan esa funcionalidad.
- Descripción general básica:
- Scancode-Workbench En esta parte, se explica cómo visualizar los resultados con la app de escritorio y los punteros a la documentación de scancode-workbench para obtener más asistencia sobre el mismo. Se agregará la documentación necesaria a scancode-workbench si es necesario.
- Deltacode Cómo Deltacode toma los resultados de scancode para determinar las diferencias a nivel de archivo entre dos bases de código.
[ 2. Cómo 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. Cómo iniciar la estructura de control de versiones], se menciona el problema del control de versiones de las opciones de línea de comandos. Lo mismo es necesario para otras partes de la documentación que también contienen comandos o información específicos de la versión que, de lo contrario, crearían confusión.
[ 2. Cómo configurar pruebas y estándares de documentación ]
La documentación ya tiene pruebas para spinx-build (compila todas las páginas y verifica si hay errores de sintaxis de Sphinx en todas partes) y la verificación de vínculos (verifica todos los vínculos a otras páginas web de la documentación) con integración continua a través de Travis-CI. (Lo agregué en esta solicitud de extracción n.° 17). Ahora necesita más verificaciones para la linting específica en texto reestructurado y otros estándares. Esto se puede lograr con restructuredtext-lint, pero necesita más investigación y se realizará como parte de mi proyecto de GSoD.
[ 3. Cómo agregar una sección “Comenzar”
Esta sección actuará 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. Cada proyecto de Aboutcode tendrá esta sección, incluidos Scancode-Toolkit, Scancode-Workbench, Deltacode y otros.
[ 4. Cómo reestructurar según las 4 funciones de documentos
La documentación existente no está estructurada de forma explícita en las 4 funciones de documentos: instructivos, guías prácticas, referencias y explicaciones. Propongo estructurarlos en consecuencia, agregando más información, explicaciones o punteros, 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 que me gustaría llevar a cabo en este proyecto. Se realizarán cambios similares en el resto de la documentación.
[ 5. Cómo reestructurar 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 de usar para los desarrolladores. Puede haber vínculos a la sección [ 2. Explicaciones sobre el análisis de código ] anterior. Esto vincula la explicación de cómo funciona el análisis al código que usa para realizarlo. Como estas carpetas contienen diferentes partes del kit de herramientas de scancode, su uso individual se puede explicar con las APIs, junto con el debate sobre cómo funciona scancode.
- [ cluecode : plugins for scanning licenses, copyrights, urls, emails ]
- [ commoncode : helper classes and functions]
- [ 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 : handles file type determinations ]
- [ scancode : CLI and API to scancode, the core part ]
En esta subsección, se incluirá información o APIs detalladas sobre estas partes del kit de herramientas de scancode en subsecciones según corresponda. Las instrucciones para desarrolladores estarán en otra página o en otra sección con subsecciones más pequeñas.
[ 6. Cómo reestructurar la página de preguntas frecuentes (Scancode-Toolkit)
Actualmente, la página de preguntas frecuentes tiene preguntas que se pueden responder mejor y deben estructurarse como guías prácticas, instructivos y documentos de referencia independientes.
- ¿Cómo funciona ScanCode? Este problema se menciona en [ 2. Explicaciones sobre el análisis de código ] y será una sección completamente independiente con muchos más detalles.
- ¿Cómo agregar nuevas reglas de licencia para mejorar la detección? Este problema ya se analizó antes en Cómo mejorar las guías prácticas 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 publicación de “guía práctica” por separado y se podría explicar con más detalle.
- ¿Cómo comenzar a desarrollar? Ya existe una página de desarrollo independiente, y la información se superpone bastante. La reestructuración de la página de desarrollo ya se analizó anteriormente.
- Pasos para lanzar una nueva versión Esto se puede transformar en una “guía práctica para lanzar una nueva versión” independiente.
- Encuentra más preguntas frecuentes que respondan preguntas genéricas sobre el proyecto y que no entren en las categorías “guía práctica” o “instructivo”.