Projeto AboutCode

Esta página contém os detalhes de um projeto de redação 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 várias opções de linha de comando para personalizar a execução da verificação, 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 com as sinalizações "--help" ou "-h". Este projeto visa fazer uma documentação completa que explique:

[ 1. Todas as opções disponíveis pela 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 de como a verificação é realizada.
    Daqui em diante, esse comportamento padrão atua como uma referência à forma como as outras opções mudam a verificação e a saída.
    Elas serão discutidas em detalhes e conterão as informações a seguir, conforme mencionado nas próximas seções.

[ 2. Iniciar estrutura de controle de versões ]

  • Meta: iniciar um sistema de controle de versões para manter corretamente as opções de várias versões/APIs e as mudanças na documentação.
  • Problema: no momento, a documentação na wiki e nas páginas ReadTheDocs é destinada a versões mais antigas e precisa de uma grande reestruturação.
  • Visão geral básica: as partes do kit de ferramentas de scancode que foram atualizadas/podem ser atualizadas na versão
  • Opções da linha de comando
  • APIs
  • Documentação (a ser iniciada) As opções da linha de comando e as APIs são alteradas nas versões e versões, e a documentação também precisa ser seguida para não causar muita 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ão 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.
  • Observação: esta parte requer uma ajuda significativa do mentor em termos de entradas e indicações 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, e as ferramentas do Aboutcode que oferecem essa funcionalidade.
  • Visão geral básica: as opções mudam o comportamento de como a verificação é executada. Um caso padrão básico será ilustrado na seção inicial [1. Todas as opções disponíveis em Command Line ] 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, e 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 em que os resultados da verificação serão gerados. Estes são -
    Esta parte vai
  • explique detalhadamente os formatos de saída
  • dar exemplos dos formatos de saída
  • forneça outros links correspondentes ao formato da saída e seu uso
  • como os resultados da verificação são armazenados nos arquivos de saída. Esse link também mostra 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 digitalização Na lista de ideias do GSoD, os formatos de saída de código de digitalização são mencionados como uma ideia de referência. Esta seção implementa o mesmo.
  • Observação: esta parte requer uma 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 da 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, e 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 ponteiros para digitalizar a documentação do workbench a fim de oferecer mais suporte. Adicionará a documentação necessária ao scancode-workbench, se necessário.
  • Deltacode Como os resultados de código de verificação são recebidos pelo Deltacode para determinar diferenças de nível de 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ão ]

Em [ 1. Opções da linha de comando do Scancode-Toolkit -> 2. Iniciar estrutura de versão] é 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. Definição de 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 pelo Travis-CI. (Adicionado por mim nesta solicitação de envio no 17) Agora ela precisa de mais verificações para inspeções específicas em texto reestruturado e outros padrões. Isso poderia ser feito com o lint de texto reestruturado, mas precisa de mais pesquisa e será feito como parte do meu projeto GSoD.

[ 3. Adição de uma seção “Como começar”]

Ele funcionará como uma seção inicial para iniciantes e conterá uma compilação dos documentos mais básicos e importantes para começar com os projetos do Aboutcode. Todo projeto 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/ponteiros, o que for necessário. Isso se aplica a todos os projetos do AboutCode e à documentação deles. Abaixo estão dois exemplos de reestruturação da documentação do Scancode-Toolkit que proponho e gostaria de realizar neste projeto. Mudanças semelhantes serão feitas no restante da documentação.

[ 5. Reestruturação da 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.

  • [ dicacode : plug-ins para varredura de licenças, direitos autorais, urls, e-mails ]
  • [ código comum : classes e funções 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 : análise de vários formatos de pacote ]
  • [ plugincode : classes para a arquitetura de plug-ins ]
  • [ summarycode : resume a verificação das licenças detectadas ]
  • [ textcode : lida com a análise de texto ]
  • [ typecode : lida com as determinações do tipo de arquivo ]
  • [scancode : CLI e API para ler o código, parte principal ]

Esta subseção vai conter informações/APIs detalhadas sobre essas partes do scancode-toolkit em subsubseções. As diretrizes de desenvolvimento estarão em outra página ou 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 devem ser estruturadas separadamente como documentos de instruções, tutoriais e referências.

  • Como funciona o ScanCode? Esse problema é mencionado em [ 2. As 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 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? Essa informação poderia ser transformada em outra postagem "Como fazer" e explicada mais detalhadamente.
  • Como começar o desenvolvimento? Já existe uma página de desenvolvimento separada, e as informações se sobrepõem bastante. A reestruturação da página de desenvolvimento já foi discutida acima.
  • Etapas para editar um novo lançamento Isso pode ser transformado em um vídeo separado, "Como cortar um novo lançamento".
  • Encontrar mais perguntas frequentes que respondem perguntas genéricas sobre o projeto e não se enquadram nas categorias “Como fazer”/“Tutorial”.