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:
- SymPy
- Redator técnico:
- Soumi7
- Nome do projeto:
- Consistência entre docstrings: documentação do Sympy (em inglês)
- Duração do projeto:
- Duração padrão (3 meses)
Project description
Resumo :
Documentação sobre o estado atual do Sympy e trabalhos anteriores :
O trabalho de criação de um guia de estilo oficial para SymPy foi concluído.
O projeto GSoD de Lauren Glattly criou um guia de estilo para docstrings SymPy, que pode ser encontrado no Guia de estilo de documentação do SymPy.
As docstrings no submódulo especial e no arquivo solvers.py foram editadas para seguir de maneira consistente as diretrizes do novo guia de estilo.
Todas as outras docstrings na base de código ainda precisavam ser editadas para obedecer ao novo guia de estilo.
Trabalho proposto :
A maioria das docstrings no SymPy ainda não segue o guia de estilo mais recente. O objetivo desse projeto seria atualizar as docstrings em todo o SymPy para que elas sigam esse guia.
Discuti o projeto com mentores. Aqui está o link da discussão.
Foi decidido que editar docstrings em toda a base de código do sympy para aderir ao guia de estilo mais recente é uma tarefa importante e que o projeto deveria ser limitado a isso.
Meu trabalho no projeto envolveria a implementação do novo guia para atualizar documentações existentes, além de coletar e solucionar outras inconsistências, como uso de linguagem ou termos.
A ordem das subseções existentes pode ser alterada ou decidida mais tarde ou como uma tarefa separada.
Demonstrar as diferenças nos resultados quando valores distintos são transmitidos aos parâmetros adicionando mais exemplos e a seção de adição de parâmetros.
Continue adicionando exemplos complicados à seção de pegadinhas e armadilhas.
Contribuições: - #17887 : trabalho no problema 17887: adição de seções de docstring ausentes no submódulo "Especial". Adicionei a seção Parâmetros e exemplos que faltava em algumas funções do submódulo "Especiales", que foi editada por L. Parabéns por seguir o guia de estilo mais recente e servir de modelo para docstrings futuros.
Este é o link para meu RP mesclado : https://github.com/sympy/sympy/pull/19334
- 19591 : a edição 19591 acompanha o guia de estilo da documentação. Adicionei um RP para editar o docstring core.sympify e seguir o guia de estilo mais recente. Adicionei explicações estruturadas e exemplos sobre o uso de parâmetros diferentes.
Aqui está um link para o RP: https://github.com/sympy/sympy/pull/19613
Metas do projeto
Cronograma Antes de 17 de agosto :
- Continue fazendo contribuições à organização.
- Conhecer melhor a documentação do usuário e a versão atual do Sympy.
- Aprender técnicas e habilidades que serão úteis para a implementação do projeto.
Vínculo comunitário (17 de agosto a 13 de setembro de 2020)
- Estabelecer um canal de comunicação e um horário (devido à diferença de horário).
- Refinar minhas metas e definir expectativas em ambos os lados.
- Discutir a ordem em que os módulos serão atualizados.
- Finalize a ordem dos módulos de edição para que eles fiquem de acordo com o guia de estilo de docstring mais recente.
Período de documentação(14 de setembro de 2020 a 30 de novembro de 2020) :
Defina metas a serem alcançadas todas as semanas, de preferência atualizando docstrings de um módulo ou submódulo por semana ou mais.
Para todos esses módulos, meu principal objetivo será adicionar seções ausentes e reestruturar as docstrings para seguir o guia de estilo mais recente. Isso inclui a demonstração dos diferentes resultados obtidos quando valores diferentes são transmitidos aos parâmetros. Todas as saídas complicadas devem ser adicionadas à seção Pegadinhas e armadilhas.
Semana 1 ( 14 a 21 de setembro) : principal
Semana 2 (22 de setembro a 29 de setembro) : funções : combinação de submódulos
Semana 3 (30 de setembro a 6 de outubro) : funções
Semana 4 (de 7 a 14 de outubro) : simplificar, criptografia
Semana 5 (15 de outubro a 21 de outubro) : diofantina
Semana 6 (de 22 de outubro a 29 de outubro):submódulo Holonômico :Operações
Semana 7 (30 de outubro a 7 de novembro) : módulo integrais(integrals.integrals), integrais de computação usando funções G Meijer
Semana 8 (de 8 a 15 de novembro) : física, funções no fim do módulo "Categorias", do Módulo de geração de código, do submódulo especial
Semana 9 (16 a 23 de novembro) : física, funções no fim do módulo "Categorias", do Módulo de geração de código, do submódulo especial
Semana 10 (de 24 a 30 de novembro) : seção de pegadinhas e armadilhas
30 de novembro a 5 de dezembro de 2020, às 18h (UTC): envio final do projeto e redação de relatórios
3 a 10 de dezembro de 2020, às 18h (UTC): envio do projeto e experiência de trabalho com mentores
A ordem dos módulos mencionados aqui pode ser alterada após uma discussão mais aprofundada com os mentores.
Conforme sugerido pelos mentores, vou me concentrar primeiro em atualizar os módulos, que são mais fáceis de atualizar, e depois passar aos mais complexos.
Por que sou a pessoa certa para este projeto?
Acredito que sou a pessoa certa para este projeto, porque tenho experiência anterior em escrita técnica com ciência da computação e sou bem versado em Git e GitHub.
Como enviei PRs para atualizar a documentação para o guia de estilo mais recente no Sympy, que foi mesclado com sucesso, estou confiante com o fluxo de trabalho e fazendo contribuições regulares.
No início, quando comecei a contribuir, encontrei alguns erros. Finalmente me acostumei a executar os testes e criar os documentos todas as vezes antes de confirmar as mudanças, já que isso é muito importante.
Estou muito confortável em contribuir com este projeto e estou ansioso por ele.