Esta página contém os detalhes de um projeto de redação técnica aceito para o Google Season of Docs.
Resumo do projeto
- Organização de código aberto:
- AboutCode
- Redator técnico:
- ayansinha
- Nome do projeto:
- Reference for Command Line Options in scancode-toolkit and Reorganize the structure of AboutCode documentation at aboutcode.readthedocs.io
- Duração do projeto:
- Padrão (3 meses)
Descrição do projeto
[ 1. Opções de linha de comando do Scancode-Toolkit ]
O Scancode-Toolkit tem várias opções de linha de comando para personalizar a forma como a verificação é realizada, o formato de saída e várias outras opções, como plug-ins pós-verificação. Essas opções não têm documentação adequada para explicá-las e só estão disponíveis usando a flag "--help" ou "-h". O objetivo deste projeto é criar uma documentação completa que explique:
[ 1. Todas as opções disponíveis na linha de comando ]
- Objetivo: uma lista exaustiva 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. Um breve gráfico/descrição de como a verificação é realizada.
A partir daqui, esse comportamento padrão serve como referência para como as outras opções mudam a verificação e a saída.
Elas serão discutidas em detalhes e vão conter as informações mencionadas nas próximas seções.
[ 2. Iniciar a estrutura de controle de versões ]
- Objetivo: iniciar um sistema de controle de versões para manter adequadamente as opções/API e as mudanças de documentação entre versões.
- Problema: atualmente, a documentação no wiki e nas páginas do ReadTheDocs é para versões mais antigas e precisa de uma grande reestruturação.
- Visão geral básica: as partes do Scancode-Toolkit que foram atualizadas/poderiam 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 acompanhar essas mudanças. Caso contrário, isso vai gerar muita confusão para os usuários. O utilitário de linha de comando [ --help ] já está atualizado para todas as mudanças 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 vai fornecer um resumo básico de como os resultados da verificação do Scancode-Toolkit podem ser usados em diferentes causas e as opções do Scancode-Toolkit que fornecem essa funcionalidade.
- Visão geral básica: esta seção oferece diferentes exemplos de cenários 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 informações e dicas 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 do Aboutcode que fornecem essa funcionalidade.
- Visão geral básica: as opções mudam o comportamento de 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 vai comparar as mudanças que todas as opções trazem para esse cenário padrão.
[ 5. Formatos de saída e exemplos ]
- 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 do Aboutcode que fornecem essa funcionalidade.
- Visão geral básica: o Scancode-Tool tem flags para especificar diferentes formatos de saída em que os resultados da verificação serão gerados. São elas:
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 ao uso dele
- como os resultados da verificação são armazenados nos arquivos de saída. Isso também se vincula a Como esses diferentes formatos são gerados, que será explicado em [ 2. Discussões explicando a verificação de código ].
[ 6. Uso comercial de formatos de saída do Scancode ]
- Objetivos: explicar os casos de uso comercial dos formatos de saída do Scancode. Na lista de ideias do GSoD, os formatos de saída do Scancode são mencionados como uma ideia de referência. Esta seção implementa o mesmo.
- Observação: esta parte exige ajuda significativa do mentor em termos de informações e dicas 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 ]
- 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 do Aboutcode que fornecem essa funcionalidade.
- Visão geral básica:
- Scancode-Workbench Esta parte explica como visualizar resultados com o app para computador e dicas para 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 do Scancode são usados pelo Deltacode para determinar as diferenças de arquivo entre duas bases de código.
[ 2. Reorganizar a estrutura da documentação do AboutCode ]
Esta parte inclui várias mudanças na documentação do Aboutcode
[ 1. Sistema de controle de versões ]
Em [ 1. Opções de linha de comando do Scancode-Toolkit -> 2. Iniciar a estrutura de controle de versões], o problema do controle de versões 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. Definir padrões e testes de documentação ]
A documentação já tem testes para spinx-build (cria todas as páginas e verifica erros de sintaxe do Sphinx) 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 #17) Agora, são necessárias mais verificações para linting específico em texto reestruturado e outros padrões. Isso pode ser feito com o restructuredtext-lint, mas precisa de mais pesquisas e será feito como parte do meu projeto GSoD.
[ 3. Adicionar uma seção "Como começar" ]
Essa seção vai servir como ponto de partida para novos usuários e vai conter uma compilação dos documentos mais básicos e importantes para começar a usar os projetos do Aboutcode. Cada projeto do Aboutcode terá essa seção, incluindo Scancode-Toolkit, Scancode-Workbench, Deltacode e outros.
[ 4. Reestruturação de acordo com as 4 funções de documento ]
A documentação atual não está estruturada explicitamente nas 4 funções de documento: tutoriais, instruções, referência e explicações. Proponho estruturá-las de acordo, adicionando mais informações/explicações/dicas, 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 proponho e gostaria de realizar neste projeto. Mudanças semelhantes serão realizadas no restante da documentação.
[ 5. Reestruturar a página de desenvolvimento (Scancode-Toolkit) ]
Mais informações sobre o código/APIs podem ser adicionadas para torná-lo mais adequado para desenvolvedores. Pode haver links para a seção [ 2. Discussões explicando a verificação de código ] acima. Isso vincula a explicação de como a verificação funciona ao código usado para realizar a verificação. Como essas pastas contêm diferentes partes 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 : plug-ins para verificação de licenças, direitos autorais, URLs, e-mails ]
- [ commoncode : classes e funções auxiliares]
- [ extractcode : extrai diferentes formatos de arquivo ]
- [ formattedcode : formatação de saída para diferentes formatos de arquivo de saída ]
- [ licensedcode : código de detecção de licença ]
- [ packagedcode : análise de vários formatos de pacote ]
- [ plugincode : classes para a arquitetura de plug-ins ]
- [ summarycode : resume a verificação em licenças detectadas ]
- [ textcode : processa a análise de texto ]
- [ typecode : processa determinações de tipo de arquivo ]
- [ scancode : CLI e API para Scancode, 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 estarão em outra página ou seção com subseções menores.
[ 6. Reestruturar a página de perguntas frequentes (Scancode-Toolkit) ]
A página de perguntas frequentes no momento tem perguntas que podem ser melhor respondidas e devem ser estruturadas como instruções, tutoriais e documentos de referência separados.
- Como o ScanCode funciona? Esse problema é referenciado em [ 2. Discussões explicando a verificação de código ] e será 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 Melhorar as instruções atuais. A documentação será movida para lá.
- Como adicionar uma nova regra de detecção de licença? Isso pode ser transformado em outra postagem de "Como fazer" separada e pode ser elaborado.
- Como começar a desenvolver? 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 lançar um novo lançamento Isso pode ser transformado em um "Como lançar um novo lançamento" separado.
- Encontre mais perguntas frequentes que respondam a perguntas genéricas sobre o projeto e não se enquadrem nas categorias "Como fazer"/"Tutorial".