Brushup of the documentation

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.

Start by reviewing the existing tutorial, user documentation, and developer documentation, focusing on the Hartree-Fock and unrestricted MP2 examples and the combined molecular/crystalline sections. Clarify the documentation structure and scope with maintainers before editing. Done means the tutorial, user material, and developer material have clearly separated purposes and the proposed theory, examples, and citations are covered.