Hacktoberfest 2026：メンテナが10月に向けて印を付けた、オープンで初心者向けの issue。 Hacktoberfest の issue を見る

Brushup of the documentation

オープン
  • 何か問題がありますか？
#8 コメント 1 件 リアクション 1 件 担当者 0 名 GitHub で見る

まだ誰も着手していません。

評価

難易度
5/5
見積もり時間
1週間以上
初心者へのやさしさ
25/100
issue の種類
ドキュメント
明瞭さ
説明が足りない
活発さ
停滞
技術スタック
tex
領域
documentation

調査の方向性

まず既存のチュートリアル、ユーザードキュメント、開発者向けドキュメントを確認し、Hartree-Fock と unrestricted MP2 の例、および分子と結晶を扱う統合セクションに重点を置きます。編集する前に、maintainer とドキュメントの構成と範囲を明確にしてください。チュートリアル、ユーザー向け資料、開発者向け資料の目的が明確に分かれており、提案された理論、例、引用が網羅されていれば完了です。

索引モデルが issue の本文から書いたものです。

説明

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.

主要言語
TeX
スター
43
フォーク
87
平均マージ
4時間 15分
マージ済み PR（30日）
1

環境構築

このプロジェクトには開発コンテナ、Dockerfile、コントリビューションガイドがありません。まず README を読み、一般的な手順ははじめてのコントリビューションガイドを参照してください。

はじめの一歩

  1. issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
  2. 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
  3. リポジトリをフォークし、ブランチを切って変更します。
  4. issue 番号を参照したプルリクエストを送ります。

pyscf/pyscf.github.io のほかの issue

pyscf/pyscf.github.io の issue をすべて見る

似ている issue

Documentation の issue をもっと見る

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。