Hacktoberfest 2026: los issues que los mantenedores marcaron para octubre, abiertos y aptos para principiantes. Explorar issues de Hacktoberfest

Brushup of the documentation

Abierto
  • ¿Algo no está bien?
#8 1 comentario 1 reacción 0 asignados Ver en GitHub

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
5/5
Tiempo estimado
Más de una semana
Aptitud para principiantes
25/100
Tipo de issue
Documentación
Claridad
Necesita aclaración
Estado de actividad
Estancado
Stack tecnológico
tex
Área
documentation

Línea de trabajo

Comienza revisando el tutorial existente, la documentación para usuarios y la documentación para desarrolladores, centrándote en los ejemplos de Hartree-Fock y unrestricted MP2 y en las secciones combinadas sobre moléculas/cristales. Aclara la estructura y el alcance de la documentación con los maintainers antes de editar. Se considera terminado cuando el tutorial, el material para usuarios y el material para desarrolladores tienen propósitos claramente separados y se han cubierto la teoría, los ejemplos y las citas propuestas.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

Documentation tends to be always the last thing developers pay attention to, and often what happens is that once a feature is complete and merged, one moves onto the next thing so documentation is never kept up to date. (A good way to avoid this is to force people to document their code by not allowing undocumented code to be merged in in the first place!)

A major issue in PySCF is that it is quite distinctively a developer code. Setting up calculations requires programming, and the user has to explicitly take care of things that happen automatically in other codes, such as the removal of linear dependencies. (I actually still look at the examples distributed as part of PySCF to set up my calculations!) This special characteristic means that documentation is hugely important.

In the old documentation, the tutorial(!) had a lot of specialized code and customizations, like

  • a function that printed out the occupations by symmetry in section 5.5.1, Hartree-Fock; this happens automatically in other codes, or
  • a hand-written implementation of unrestricted MP2 in section 5.5.2

While these examples underline the flexibility of PySCF, I'm not sure their proper place is in the tutorial chapter; a much better place would be in the developer documentation. The tutorial section should just consist of straightforward examples for professional quantum chemists, that is, people who already know what they want to do, and just want to see how to run that calculation with PySCF.

Of course, not all bases can be covered in the tutorial, so also the user documentation will have several examples on how to run a bit more complicated calculations with PySCF. As in the manuals for other programs, the user documentation should contain at least a minimal level of theory of what is done in the code and how the equations are solved along with any relevant citations.

Another issue with the current version of the documentation is that molecular and crystalline calculations are discussed together, which makes the documentation extremely hard to follow. The discussion should be started out with molecules - which are easier - and then continue in a new section to crystals, where the differences to molecular calculations can be discussed.

The user documentation should also not go too deep into the code. The code design belongs in the developer documentation section. The developer documentation is the "hard-core" version, with the class structures, coding styles, etc. The section builds on top of the user documentation, so the theory already presented in the user section does not need to be repeated; however, algorithmic details should be discussed at a deeper level in the developer section.

Lenguaje dominante
TeX
Estrellas
43
Forks
87
Sin PR fusionados en 30 d

Preparar el entorno

Este proyecto no incluye contenedor de desarrollo, Dockerfile ni guía de contribución, así que la configuración corre por tu cuenta: empieza por su README y consulta nuestra guía para la primera contribución para los pasos generales.

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de pyscf/pyscf.github.io

Todos los issues de pyscf/pyscf.github.io

Issues similares

Más issues de Documentation

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.