Projeto AboutCode

Esta página contém os detalhes de um projeto de escrita técnica aceito para a temporada de documentos do Google.

Resumo do projeto

Organização de código aberto:
AboutCode
Redator técnico:
ayansinha
Nome do projeto:
Referência para opções de linha de comando no scancode-toolkit e reorganizar a estrutura da documentação do AboutCode em aboutcode.readthedocs.io
Duração do projeto:
Duração padrão (3 meses)

Project description

[1) Opções da linha de comando do Scancode-Toolkit ]

O Scancode-Toolkit tem um host de opções da linha de comando para personalizar como a verificação é realizada, o formato de saída e várias outras opções, como plug-ins pós-verificação. No momento, essas opções não têm documentação adequada para explicá-las e estão disponíveis apenas por meio dos sinalizadores "--help" ou "-h". O objetivo deste projeto é reunir uma documentação completa que explique:

[1) Todas as opções disponíveis na linha de comando ]

  • Meta: uma lista completa de todas as opções possíveis pela linha de comando.
  • Visão geral básica: primeiro, as opções de verificação padrão são discutidas, com um exemplo da saída. Um breve gráfico/descrição sobre como a verificação é realizada.
    Daqui em diante, esse comportamento padrão atua como uma referência a como as outras opções alteram a verificação e a saída.
    Essas informações serão discutidas em detalhes e vão conter as informações a seguir, conforme mencionado nas próximas seções.

[2) Iniciar estrutura de controle de versão ]

  • Meta: iniciar um sistema de controle de versões para manter corretamente as opções de várias versões/mudanças na API e na documentação.
  • Problema: no momento, a documentação no wiki e nas páginas ReadTheDocs são de versões mais antigas e precisam de uma grande reestruturação.
  • Visão geral básica: as partes do scancode-toolkit que foram atualizadas/podem ser atualizadas na versão são
  • Opções da linha de comando
  • APIs
  • Documentação (a ser iniciada) As opções da linha de comando e as APIs foram alteradas nas versões e versões, e a documentação também precisa estar de acordo. Caso contrário, isso criará uma grande confusão para os usuários. O utilitário de linha de comando [ --help ] já foi atualizado para quaisquer alterações nas opções e pode ser usado para replicar o controle de versões na documentação.

[3) como essas opções podem ser usadas em diferentes casos ]

  • Objetivo: esta seção fornecerá um resumo básico de como os resultados da verificação do scancode-toolkit podem ser usados em diferentes causas e das opções do Scancode-Toolkit que fornecem essa funcionalidade.
  • Visão geral básica: esta seção apresenta diferentes exemplos de cenários de uso e as opções recomendadas para cada um deles.
  • Observação: esta parte requer uma ajuda significativa do mentor em termos de entradas e ponteiros para vários casos de uso do Scancode-Toolkit.

[ 4. O que essas opções mudam na verificação e na saída ]

  • Objetivo: esta seção fornecerá um resumo básico de como os resultados da verificação do scancode-toolkit podem ser usados em diferentes causas, bem como as ferramentas do Aboutcode que oferecem essa funcionalidade.
  • Visão geral básica: as opções alteram o comportamento de execução da verificação. Um caso padrão básico será ilustrado na seção inicial [ 1. Todas as opções disponíveis na linha de comando ] e esta seção compararão as alterações que todas as opções trazem a esse cenário padrão.

[ 5. Formatos de saída e seus exemplos ]

  • Objetivo: esta seção fornecerá um resumo básico de como os resultados da verificação do scancode-toolkit podem ser usados em diferentes causas, bem como as ferramentas do Aboutcode que oferecem essa funcionalidade.
  • Visão geral básica: o Scancode-Tool tem sinalizações para especificar diferentes formatos de saída nos quais os resultados da verificação serão gerados. Estes são os seguintes:
    Esta parte vai
  • explicar em detalhes os formatos de saída
  • dar exemplos sobre os formatos de saída
  • fornecer outros links correspondentes ao formato de saída e seu uso
  • como os resultados da verificação são armazenados nos arquivos de saída. Esse link também está relacionado a Como esses diferentes formatos são gerados, o que será explicado em [ 2. Discussões explicando a verificação de código ].

[ 6. Uso comercial de formatos de saída de scancode ]

  • Objetivos: explicar os casos de uso comerciais dos formatos de saída de código de verificação Na lista de ideias do GSoD, os formatos de saída de código de verificação são mencionados como uma ideia de referência. Esta seção implementa o mesmo.
  • Observação: esta parte requer ajuda significativa do mentor em termos de entradas e indicações para vários casos de uso de negócios do Scancode-Toolkit.

[ 7. Como essas saídas são usadas por outros projetos AboutCode para mais análises ]

  • Objetivo: esta seção fornecerá um resumo básico de como os resultados da verificação do scancode-toolkit podem ser usados em diferentes causas, bem como as ferramentas do Aboutcode que oferecem essa funcionalidade.
  • Visão geral básica:
  • Scancode-Workbench Esta parte explica a visualização de resultados com o app para computador e indicações para a documentação do scancode-workbench a fim de receber mais suporte. Adicionará a documentação necessária ao scancode-workbench, se necessário.
  • Deltacode Como os resultados de scancode são obtidos pelo Deltacode para determinar as diferenças no nível do arquivo entre duas bases de código.

[2) Reorganizar a estrutura da documentação do AboutCode ]

Essa parte inclui várias mudanças na documentação do Aboutcode

[1) Sistema de controle de versões ]

Em [ 1. Opções da linha de comando do Scancode-Toolkit -> 2. Iniciar estrutura de controle de versões] é mencionado o problema do controle de versões das opções da linha de comando. O mesmo é necessário para outras partes da documentação que contenham comandos/informações específicas da versão que, de outra forma, criariam confusão.

[2) Como configurar padrões e testes de documentação ]

A documentação já tem testes de spinx-build (compila todas as páginas e verifica se há erros de sintaxe do Sphinx) e verificação de links (verifica todos os links para outras páginas da Web da documentação) com integração contínua por meio do Travis-CI. (Adicionado por mim nesta solicitação de envio no 17) Agora são necessárias mais verificações para inspeção específica em texto reestruturado e outros padrões. Isso poderia ser feito com o reestruturado text-lint, mas precisa de mais pesquisa e será feito como parte do meu projeto GSoD.

[3) Adição da seção “Como começar”]

Ela servirá como seção inicial para iniciantes e conterá uma compilação dos documentos mais básicos e importantes para começar a usar projetos do Aboutcode. Cada projeto do Aboutcode terá essa seção, incluindo Scancode-Toolkit, Scancode-Workbench, Deltacode e outras.

[ 4. Reestruturação de acordo com as quatro funções do documento ]

A documentação atual não está explicitamente estruturada nas quatro funções do documento: tutoriais, instruções, referências e explicações. Proponho estruturá-los adequadamente, adicionando mais informações/explicações/apontadores conforme necessário. Isso se aplica a todos os projetos AboutCode e à documentação deles. Abaixo estão dois exemplos de reestruturação da documentação do Scancode-Toolkit que proponho e gostaria de continuar neste projeto. Mudanças semelhantes serão feitas no restante da documentação.

[ 5. Como reestruturar a página de desenvolvimento (Scancode-Toolkit) ]

Mais informações sobre o código/APIs podem ser adicionadas para facilitar o desenvolvimento. Pode haver links para a página [ 2. Discussões explicando a seção Verificação de código ] acima. Isso vincula a explicação de como a verificação funciona ao código usado para executá-la. Assim como essas pastas contêm diferentes partes do scancode-toolkit, seu uso individual pode ser elaborado com as APIs, em conjunto com a Discussão sobre como o scancode funciona.

  • [ cluecode : plug-ins para verificar licenças, direitos autorais, URLs, e-mails ]
  • [ código comum : funções e classes auxiliares]
  • [Extractcode : extrai diferentes formatos de arquivo ]
  • [ formattedcode : formatação de saída para diferentes formatos de arquivos de saída ]
  • [licensecode : código de detecção de licença ]
  • [ packagecode : analisando diversos formatos de pacotes ]
  • [ plugincode : classes para a arquitetura de plug-ins ]
  • [ summarycode : resume a verificação nas licenças detectadas ]
  • [ textcode : lida com a análise de texto ]
  • [ typecode : manipula as determinações do tipo de arquivo ]
  • [ scancode : CLI e API para verificar o código, a parte principal ]

Esta subseção vai conter informações/APIs detalhadas sobre essas partes do scancode-toolkit nas subsubseções. As diretrizes de desenvolvimento estarão em outra página ou em outra seção com subseções menores.

[ 6. Reestruturação da página de perguntas frequentes (Scancode-Toolkit) ]

No momento, a página de perguntas frequentes tem perguntas que podem ser mais bem respondidas e deve ser estruturada separadamente como documentos de instruções, tutoriais e referências.

  • Como funciona o ScanCode? Esse problema é mencionado em [ 2. Discussões explicando a verificação de código ] serão uma seção totalmente separada com muito mais detalhes.
  • Como adicionar novas regras de licença para detecção aprimorada? Esse problema já foi discutido antes em "Como melhorar as instruções" atual, a documentação será movida para lá.
  • Como adicionar uma nova regra de detecção de licença? Isso poderia ser transformado em outra postagem de "Como fazer" separadamente e de forma mais elaborada.
  • Como começar o desenvolvimento? Já existe uma página de desenvolvimento separada, e as informações se sobrepõem muitas vezes. A reestruturação da página de desenvolvimento já foi discutida acima.
  • Etapas para fazer um novo lançamento Isso pode ser transformado em um vídeo separado "Como cortar um lançamento".
  • Encontre mais perguntas frequentes que respondem a perguntas genéricas sobre o projeto e não se enquadram nas categorias “Como fazer”/”Tutorial”.