Proyecto AboutCode

Esta página contiene los detalles de un proyecto de redacción técnico aceptado para Google Season of Docs.

Resumen del proyecto

Organización de código abierto:
AboutCode
Redactor técnico:
amansinha
Nombre del proyecto:
Referencia para las opciones de línea de comandos en scancode-toolkit y sobre cómo reorganizar 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 serie de opciones de línea de comandos para personalizar la forma en que se realiza el análisis, el formato de salida y muchas otras opciones, como complementos posteriores al análisis. Por el momento, estas opciones no tienen la documentación adecuada para explicarlas y solo están disponibles mediante las marcas “--help” o “-h”. El objetivo de este proyecto es elaborar una 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 búsqueda predeterminadas, con un ejemplo del resultado. Una imagen o descripción breve sobre cómo se realiza el análisis
    De ahora en adelante, este comportamiento predeterminado actúa como referencia a cómo las otras opciones cambian el análisis y el resultado.
    Estos detalles se analizarán en detalle y incluirán la siguiente información, que se menciona en las secciones siguientes.

[ 2. Inicia la estructura del control de versiones ]

  • Objetivo: Iniciar un sistema de control de versiones para mantener adecuadamente las opciones de lanzamientos cruzados, los cambios en la API y la documentación.
  • Problema: actualmente la documentación de la wiki y las páginas de ReadTheDocs son para versiones anteriores y requiere una gran reestructuración.
  • Descripción general básica: Las partes de scancode-toolkit que se actualizaron o podrían actualizarse en la versión
  • Opciones de línea de comandos
  • APIs
  • Documentación (que se debe iniciar) Las opciones de la línea de comandos y las APIs se modifican en las versiones y las actualizaciones, y la documentación también debe seguirse; de lo contrario, se generará 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 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: Esta sección proporcionará un resumen básico de cómo se pueden utilizar los resultados del análisis 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 uso y las opciones recomendadas para esas situaciones.
  • Nota: Esta parte requiere una ayuda significativa del mentor en términos de información sobre diversos casos de uso y consejos sobre Scancode-Toolkit.

[ 4. Qué cambian estas opciones en Scan y Output ]

  • Objetivo: Esta sección proporcionará un resumen básico de cómo se pueden utilizar los resultados del análisis de scancode-toolkit en diferentes causas y las herramientas Aboutcode que proporcionan esa funcionalidad.
  • Descripción general básica: Las opciones cambian el comportamiento de cómo se realiza la búsqueda. En la sección inicial, se ilustrará un caso predeterminado básico [ 1. Todas las opciones disponibles a través de Command Line ] y esta sección compararán los cambios que todas las opciones aportan a este escenario predeterminado.

[ 5. Formatos de salida y sus ejemplos ]

  • Objetivo: Esta sección proporcionará un resumen básico de cómo se pueden utilizar los resultados del análisis de scancode-toolkit en diferentes causas y las herramientas 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. Estas son -
    En esta parte,
  • explicar en detalle los formatos de salida
  • da ejemplos sobre los formatos de salida
  • Brindaremos 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. Esto también incluye un vínculo a Cómo se generan estos diferentes formatos, que se explicará en [ 2. Debates en los que se explica el escaneo de código ].

[ 6. Uso comercial de los formatos de salida de Scancode ]

  • Objetivos: Explicar los casos de uso comerciales de los formatos de salida de Scancode En la lista de ideas de GSoD, se menciona los formatos de salida de Scancode como idea de referencia. En esta sección se implementa lo mismo.
  • Nota: Esta parte requiere una gran ayuda del mentor en términos de información sobre diversos casos de uso empresariales de Scancode-Toolkit y sugerencias sobre 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 utilizar los resultados del análisis de scancode-toolkit en diferentes causas y las herramientas Aboutcode que proporcionan esa funcionalidad.
  • Descripción general básica:
  • Scancode-Workbench En esta parte, se explican los resultados de la visualización con la app de escritorio y los punteros a la documentación de scancode-workbench para obtener más compatibilidad con esto. Se agregará la documentación requerida a scancode-workbench si es necesario.
  • Deltacode: Indica cómo Deltacode toma los resultados de escaneo de código para determinar las diferencias a nivel de archivo entre dos bases de código.

[ 2. Reorganiza la estructura de la documentación de AboutCode].

Esta parte incluye una serie de cambios realizados en la documentación de Aboutcode.

[ 1. Sistema de control de versiones ]

En [ 1. Opciones de línea de comandos de Scancode-Toolkit -> 2. Initiate Versioning Structure] se menciona el problema del control de versiones de las opciones de la línea de comandos. Lo mismo es necesario para otras partes de la documentación que también contengan información o comandos específicos de la versión que, de lo contrario, crearían confusión.

[ 2. Configuración de los estándares y las pruebas de la documentación ]

La documentación ya tiene pruebas para la compilación de spinx (compila todas las páginas y comprueba si hay errores de sintaxis de Sphinx en todo el documento) y verificación de vínculos (verifica todos los vínculos a otras páginas web en la documentación) con integración continua a través de Travis-CI. (Agregada por mí en esta solicitud de extracción n° 17) Ahora necesita más comprobaciones para análisis con lint específicos en Texto reestructurado y otros estándares. Esto podría lograrse con reestructuración del texto lint, pero necesita más investigación y se realizará como parte de mi proyecto de GSoD.

[ 3. Agrega una sección de “Primeros pasos”.]

Esta será una sección de inicio para los principiantes y contendrá una compilación de los documentos más importantes y básicos para comenzar con los proyectos Aboutcode. Todos los proyectos Aboutcode tendrán esta sección, que incluye Scancode-Toolkit, Scancode-Workbench, Deltacode y otras.

[ 4. Reestructuración de acuerdo con las 4 funciones de documentos ]

La documentación existente no está estructurada de manera explícita en las 4 funciones del documento: instructivos, instructivos, referencia y explicaciones. Propongo estructurarlos como corresponde y agregar 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 incluyen dos ejemplos de la reestructuración de la documentación de Scancode-Toolkit que propongo y que me gustaría continuar en este proyecto. Se realizarán 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 y las APIs para que sea más fácil de usar para los desarrolladores. Puede haber vínculos al [ 2. Debates en los que se explica la sección de escaneo de código ] anterior. Esto vincula la explicación de cómo funciona el análisis con el código que usa para realizarlo. Al igual que estas carpetas contienen diferentes partes de scancode-toolkit, su uso individual se puede profundizar con las API, junto con la discusión sobre cómo funciona scancode.

  • [ código de pista : complementos para escanear licencias, derechos de autor, URL, correos electrónicos ]
  • [commoncode : clases auxiliares y funciones]
  • [ extractcode : extrae diferentes formatos de archivo ]
  • [ formattedcode : formato de salida para diferentes formatos de archivo de salida ]
  • [código con licencia : código de detección de licencia ]
  • [ packcode : análisis de distintos formatos de paquetes ]
  • [código de complemento : clases para la arquitectura de complementos ]
  • [ summarycode : resume el análisis de las licencias detectadas ]
  • [código de texto : controla el análisis de texto ]
  • [ typecode : controla las determinaciones del tipo de archivo ]
  • [Scancode : CLI y API para escanear, la parte central ]

Esta subsección contendrá información y APIs detalladas sobre estas partes de scancode-toolkit en subsecciones correspondientes. Las pautas de desarrollo estarán allí en otra página u otra sección con subsecciones más pequeñas.

[ 6. Reestructuración de la página de preguntas frecuentes (Scancode-Toolkit) ]

En la actualidad, la página de Preguntas frecuentes tiene preguntas que se pueden responder mejor y deben estructurarse como instructivos, instructivos y documentos de referencia independientes.

  • ¿Cómo funciona ScanCode? Se hace referencia a este problema en [ 2. Los debates en los que se explica el análisis de código ] serán una sección completamente independiente con muchos más detalles.
  • ¿Cómo agregar nuevas reglas de licencia para una detección mejorada? Este problema ya se analizó en la mejora de los instructivos existentes, la documentación se moverá allí.
  • ¿Cómo puedo agregar una nueva regla de detección de licencias? Esto se puede convertir en otra publicación de “Instructivo” por separado y se puede profundizar.
  • Cómo dar tus primeros pasos con el desarrollo 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 debatió anteriormente.
  • Pasos para lanzar un nuevo lanzamiento Esto se puede transformar en un instructivo independiente para publicar un nuevo lanzamiento.
  • Encuentra más preguntas frecuentes que respondan preguntas genéricas sobre el proyecto y no entra en las categorías “Instructivo”/“Instructivo”.