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:
- SymPy
- Redator técnico:
- Soumi7
- Nome do projeto:
- Consistência entre docstrings: documentação do Sympy
- Duração do projeto:
- Duração padrão (três meses)
Project description
Resumo :
Atual estado da documentação do Sympy e trabalhos anteriores :
O trabalho de criação de um guia de estilo oficial para o SymPy foi concluído.
O projeto GSoD de Lauren Glattly criou um guia de estilo para docstrings do SymPy, que pode ser encontrado no guia de estilo de documentação do SymPy.
Os docstrings no submódulo especial e no arquivo solvers.py foram editados para seguir de forma consistente as diretrizes do novo guia de estilo.
Todos os outros docstrings na base de código ainda precisavam ser editados para obedecer ao novo guia de estilo.
Trabalho proposto :
A maioria dos docstrings no SymPy ainda não segue o guia de estilo mais recente. O objetivo deste projeto é atualizar os docstrings em todo o SymPy para aderir a este guia.
Discuti o projeto com mentores. Este é um link para a discussão.
Foi decidido que editar docstrings em toda a base de código do sympy para seguir o guia de estilo mais recente é uma grande tarefa e o projeto deve se limitar a ela.
Meu trabalho no projeto envolveria a implementação do novo guia para atualizar os docstrings existentes, além de coletar e resolver outras inconsistências, como o uso da linguagem ou termos.
A ordem das subseções atuais pode ser alterada ou decidida mais tarde ou como uma tarefa separada.
Demonstrar as diferenças nos resultados quando valores diferentes são transmitidos aos parâmetros adicionando mais exemplos e a seção de parâmetros.
Continue adicionando exemplos complicados à seção de armadilhas e armadilhas.
Contribuições: - #17887 : Trabalho no problema no 17887: adição de seções de docstring ausentes no submódulo Especial. Adicionei a seção "Parâmetros e exemplos" ausente em algumas funções do submódulo "Especiais", que foi editado por L. Glattly para seguir o guia de estilo mais recente e servir como modelo para futuros docstrings.
Este é o link da minha PR mesclada : https://github.com/sympy/sympy/pull/19334
- #19591 : o problema #19591 rastreia o guia de estilo da documentação. Adicionei um PR para editar o docstring core.sympify para seguir o guia de estilo mais recente. Adicionei explicações e exemplos estruturados sobre o uso de parâmetros diferentes.
Este é um link para a PR: https://github.com/sympy/sympy/pull/19613
Metas do projeto
Cronograma Antes de 17 de agosto :
- Continue fazendo contribuições para a organização.
- Conheça melhor a documentação do usuário e a versão atual do sympy.
- Aprenda técnicas e habilidades que serão úteis durante a implementação do projeto.
Vinculação com a comunidade (17 de agosto a 13 de setembro de 2020)
- Configure um canal de comunicação e um horário (devido à diferença de fuso horário).
- Refinar minhas metas e definir as expectativas de ambos os lados.
- Discutir a ordem em que os módulos serão atualizados.
- Finalize a ordem de edição dos módulos para que eles sigam o guia de estilo mais recente de docstrings.
Período de documentação(14 de setembro a 30 de novembro de 2020) :
Defina metas para alcançar todas as semanas, de preferência atualizando os docstrings de um módulo ou submódulo por semana ou mais.
Para todos esses módulos, meu objetivo principal será adicionar seções ausentes e reestruturar os docstrings para seguir o guia de estilo mais recente. Isso inclui demonstrar os diferentes resultados obtidos quando valores diferentes são transmitidos aos parâmetros. Todas as saídas complicadas serão adicionadas à seção "Dificuldades e armadilhas".
Semana 1 ( 14 a 21 de setembro) : núcleo
Semana 2 (22 a 29 de setembro) : Funções : submódulos combinados
Semana 3 (30 de setembro a 6 de outubro) : funções
Semana 4 (7 a 14 de outubro) : Simplify, Crypto
Semana 5 (15 a 21 de outubro) : diofantina
Semana 6 (22 a 29 de outubro):Holonomic :Operations submodule
Semana 7 (30 de outubro a 7 de novembro) : módulo Integrals(integrals.integrals), Integrals de computação usando Meijer G-Functions
Semana 8 (8 a 15 de novembro) : física, funções no final do módulo de categorias, módulo de geração de código, submódulo especial
Semana 9 (16 a 23 de novembro) : física, funções no final do módulo de categorias, módulo de geração de código, submódulo especial
Semana 10 (24 a 30 de novembro) : seção de armadilhas e perigos
30 de novembro a 5 de dezembro de 2020, às 18h (Horário de Brasília): envio do projeto final e redação do relatório
De 3 a 10 de dezembro de 2020, às 18h (UTC): envio do projeto de sucesso e da experiência de trabalho com mentores
A ordem dos módulos mencionados aqui pode ser alterada após mais discussões com os mentores.
Como sugerido pelos mentores, vou me concentrar primeiro nos módulos mais fáceis de atualizar e depois nos complexos.
Por que sou a pessoa certa para esse projeto?
Acredito que ser 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 com git e github.
Como enviei PRs para atualizar a documentação do guia de estilo mais recente no sympy, que foram mescladas com sucesso, tenho confiança no fluxo de trabalho e faço contribuições regulares.
No início, quando comecei a contribuir, enfrentei alguns erros. Finalmente me acostumei a executar os testes e criar os documentos sempre antes de confirmar as mudanças, porque isso é muito importante.
Estou muito à vontade para contribuir com este projeto e estou ansioso por isso.