Projeto AboutCode

Esta página contém os detalhes de um projeto de redação técnica aceito para a Google Season of Docs.

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 de linha de comando do Scancode-Toolkit ]

O Scancode-Toolkit tem várias opções de 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 e só estão disponíveis com a flag "--help" ou "-h". O objetivo deste projeto é fazer uma documentação completa que explique:

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

  • Objetivo: uma lista completa de todas as opções possíveis na 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. É uma breve descrição/gráfico sobre como a verificação é realizada.
    A partir de agora, esse comportamento padrão vai servir de referência para entender como as outras opções mudam a verificação e a saída.
    Vamos discutir isso em detalhes e conter as seguintes informações, conforme mencionado nas próximas seções.

[ 2. Iniciar a estrutura de controle de versão ]

  • Objetivo: iniciar um sistema de controle de versões para manter adequadamente as opções de várias versões/APIs e as mudanças na documentação.
  • Problema: atualmente, a documentação no wiki e nas páginas do ReadTheDocs são para 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 de linha de comando
  • APIs
  • Documentação (a ser iniciada) As opções de linha de comando e as APIs são alteradas em versões e lançamentos, e a documentação também precisa seguir, caso contrário, vai gerar uma grande confusão para os usuários. O utilitário de linha de comando [ --help ] já foi atualizado para qualquer alteração 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 oferecem essa funcionalidade.
  • Visão geral básica: esta seção apresenta diferentes exemplos de casos de uso e quais opções são recomendadas nesses cenários.
  • Observação: esta parte exige ajuda significativa do mentor em termos de entradas e indicadores sobre 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 vai fornecer um resumo básico de como os resultados da verificação do scancode-toolkit podem ser usados em diferentes causas e as ferramentas Aboutcode que oferecem essa funcionalidade.
  • Visão geral básica: as opções mudam o comportamento da forma como a verificação é realizada. Um caso padrão básico será ilustrado na seção principal [ 1. Todas as opções disponíveis na linha de comando ] e esta seção vão comparar as mudanças que todas as opções trazem para esse cenário padrão.

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

  • Objetivo: esta seção vai fornecer um resumo básico de como os resultados da verificação do scancode-toolkit podem ser usados em diferentes causas e as ferramentas Aboutcode que oferecem essa funcionalidade.
  • Visão geral básica: a ferramenta Scancode tem flags para especificar diferentes formatos de saída em que os resultados da verificação serão gerados. São -
    Esta parte vai
  • explicar em detalhes os formatos de saída
  • dê exemplos dos formatos de saída
  • dar outros links correspondentes ao formato de saída e ao uso dele
  • como os resultados da verificação são armazenados nos arquivos de saída. Isso também se conecta a Como esses formatos diferentes são gerados, que será explicado em [ 2. Discussões que explicam a verificação de código ].

[ 6. Uso comercial de formatos de saída de código de barras ]

  • Metas: explicar os casos de uso comercial dos formatos de saída de código de barras Na lista de ideias do GSoD, os formatos de saída de código de barras são mencionados como uma ideia de referência. Esta seção implementa o mesmo.
  • Observação: essa parte exige ajuda significativa do mentor em termos de informações e indicações sobre vários casos de uso comercial do Scancode-Toolkit.

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

  • Meta: 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 Aboutcode que fornecem essa funcionalidade.
  • Visão geral básica:
  • Scancode-Workbench Esta parte explica como visualizar resultados com o app para computador e como acessar a documentação do Scancode-Workbench para mais suporte. Vamos 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 de arquivo entre duas bases de código.

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

Esta parte inclui uma série de mudanças na documentação do Aboutcode

[ 1. Sistema de controle de versões ]

In [ 1. Opções de linha de comando do Scancode-Toolkit: -> 2. Inicia a estrutura de controle de versão] o problema de controle de versão das opções de linha de comando é mencionado. O mesmo é necessário para outras partes da documentação que também contêm comandos/informações específicos da versão que, de outra forma, criariam confusão.

[ 2. Como definir padrões de documentação e testes ]

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

[ 3. Como adicionar uma seção "Como começar"]

Isso servirá como uma seção inicial para iniciantes e conterá uma compilação dos documentos mais básicos e importantes para começar a usar projetos sobre código. Todos os projetos do Aboutcode terão essa seção, incluindo o Scancode-Toolkit, o Scancode-Workbench, o Deltacode e outros.

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

A documentação atual não está estruturada de forma explícita nas quatro funções do documento: tutoriais, instruções, referência e explicações. Proponho estruturar essas informações, adicionando mais informações/explicações/indicações, o que for necessário. Isso vale para todos os projetos do AboutCode e a documentação deles. Confira abaixo dois exemplos da reestruturação da documentação do Scancode-Toolkit que eu proponho e gostaria de continuar neste projeto. Mudanças semelhantes serão realizadas no restante da documentação.

[ 5. Restruturação da página de desenvolvimento (Scancode-Toolkit) ]

Mais informações sobre o código/APIs podem ser adicionadas para torná-lo mais amigável ao desenvolvedor. Pode haver links para o [ 2. Discussões que explicam a seção acima sobre a verificação de código. Isso vincula a explicação de como o processo funciona ao código usado para executá-lo. Como essas pastas contêm partes diferentes do scancode-toolkit, o uso individual delas pode ser elaborado com as APIs, em conjunto com a discussão sobre como o scancode funciona.

  • [ cluecode : plugins for scanning licenses, copyrights, urls, emails ]
  • [ commoncode : helper classes and functions]
  • [ extractcode : extrai diferentes formatos de arquivo ]
  • [ formattedcode : formatação de saída para diferentes formatos de arquivo de saída ]
  • [Licensingcode : Código de detecção de licença ]
  • [ packagedcode : parsing various package formats ]
  • [plugincode : classes para a arquitetura de plug-ins ]
  • [ summarycode : summarizes scan on detected licenses ]
  • [ código de texto : lida com a análise de texto ]
  • [typecode : lida com determinações do tipo de arquivo ]
  • [ scancode : CLI e API para código de verificação, a parte principal ]

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

[ 6. Restructuring the FAQ page (Scancode-Toolkit) ]

A página de perguntas frequentes atual tem perguntas que podem ser respondidas melhor e devem ser estruturadas como documentos separados de tutoriais, instruções e referência.

  • Como o ScanCode funciona? Esse problema é mencionado em [ 2. As discussões que explicam 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 a detecção aprimorada? Esse problema já foi discutido em "Como melhorar os tutoriais". A documentação será movida para lá.
  • Como adicionar uma nova regra de detecção de licença? Isso pode ser feito em outra postagem "Como fazer" separadamente e pode ser elaborado.
  • 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 cortar uma nova versão Isso pode ser transformado em um "Como cortar uma nova versão" separado.
  • Encontre mais perguntas frequentes que respondem a perguntas genéricas sobre o projeto e não se enquadram nas categorias “Como fazer”/“Tutorial”.