Proyecto AboutCode

Esta página contiene los detalles de un proyecto de redacción técnica aceptado para la temporada de Documentos de Google.

Resumen del proyecto

Organización de código abierto:
AboutCode
Escritor técnico:
ayansinha
Nombre del proyecto:
Referencia para 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 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. Actualmente, estas opciones no tienen la 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 búsqueda predeterminadas con un ejemplo del resultado. Una descripción o gráfico breve de cómo se realiza la búsqueda
    A partir de ese momento, este comportamiento predeterminado actúa como referencia a 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 adecuadamente las opciones de actualización cruzada/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 reestructuración importante.
  • Descripción general básica: Las partes de scancode-toolkit que se actualizaron/podrían actualizarse en versión son
  • Opciones de línea de comandos
  • APIs
  • Documentación (se debe iniciar) Las opciones de línea de comandos y las APIs cambian en las versiones y actualizaciones, y la documentación también debe seguirse. De lo contrario, los usuarios tendrán una gran confusión. 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 distintos casos ]

  • 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 sobre las opciones de Scancode-Toolkit que brindan esa funcionalidad.
  • Descripción general básica: En esta sección, se proporcionan diferentes ejemplos de situaciones de casos de uso y las opciones recomendadas para 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 sugerencias.

[ 4. Qué cambian estas opciones en la búsqueda y en la salida ]

  • Objetivo: esta sección proporciona un resumen básico de cómo se pueden usar los resultados del análisis de scancode-toolkit en diferentes causas, y las herramientas Aboutcode que proporcionan esa funcionalidad.
  • Descripción general básica: estas opciones cambian el comportamiento de la búsqueda. En la sección inicial, se ilustrará un caso predeterminado básico [ 1. En todas las opciones disponibles en la línea de comandos ], en esta sección, se compararán los cambios que todas las opciones aportan a este escenario predeterminado.

[ 5. Formatos de salida y sus ejemplos ]

  • Objetivo: esta sección proporciona un resumen básico de cómo se pueden usar 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 que especifican los diferentes formatos de salida en los que se generarán los resultados del análisis. Estos son los siguientes:
    En esta parte,
  • explicar en detalle los formatos de salida
  • Das ejemplos sobre los formatos de salida
  • proporcionar otros enlaces 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. Debates en los que se explica el análisis de código ].

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

  • Objetivos: Explicar los casos de uso empresariales 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 gran ayuda del mentor en términos de entradas sobre varios casos de uso empresariales de Scancode-Toolkit y sugerencias.

[ 7. Cómo otros proyectos de AboutCode usan estos resultados para realizar un análisis más detallado ]

  • Objetivo: esta sección proporciona un resumen básico de cómo se pueden usar 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 explica cómo visualizar resultados con la app de escritorio y punteros a la documentación de scancode-workbench para obtener más compatibilidad con esto. Agregaremos la documentación requerida a scancode-workbench si es necesario.
  • Deltacode: Indica cómo Deltacode toma los resultados de código de análisis para determinar las diferencias de 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 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 otro modo, crearían confusión.

[ 2. Cómo establecer estándares y pruebas de documentación

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

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

Esto servirá como una sección inicial para los novatos y contendrá una recopilación de los documentos más básicos e importantes para empezar a usar los proyectos de Aboutcode. Todos los proyectos Aboutcode tendrán esta sección, incluidas Scancode-Toolkit, Scancode-Workbench, Deltacode y otras.

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

La documentación existente no se estructura explícitamente en las 4 funciones del documento: instructivos, instructivos, referencia y explicaciones. Propongo estructurarlos en consecuencia y agregar más información, explicaciones o punteros según sea necesario. Esto se aplica a todos los proyectos AboutCode y su documentación. A continuación, se incluyen dos ejemplos de la reestructuración de la documentación del 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 del funcionamiento del análisis con el código que se usa para realizarlo. Al igual que estas carpetas contienen diferentes partes de scancode-toolkit, su uso individual se puede desarrollar con las APIs, junto con el análisis 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 licencias ]
  • [ packcode : analizar varios formatos de paquetes ]
  • [código_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 principal ]

Esta subsección contendrá información detallada y las API sobre estas partes de scancode-toolkit en subsubsecciones según corresponda. Las pautas de Desarrollo estarán 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 este momento, la página de Preguntas frecuentes tiene preguntas que se pueden responder mejor y debe estructurarse como instructivos, instructivos y documentos de referencia por separado.

  • ¿Cómo funciona ScanCode? Se hace referencia a este problema en [ 2. Debates en los que se explica el análisis de código ] y serán una sección completamente separada en muchos más detalles.
  • ¿Cómo agregar nuevas reglas de licencia para la detección mejorada? Este problema ya se discutió anteriormente en la sección de 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 incluir en otra publicación de "Instructivos" por separado y podría profundizarse al respecto.
  • ¿Cómo comenzar a usar Desarrollo? Ya hay 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 "Cómo crear un nuevo lanzamiento" independiente.
  • Encuentra más preguntas frecuentes que respondan preguntas genéricas sobre el proyecto y no entra en las categorías «Instructivo»/«Instructivo».