Questionnaire about documentation

[yupix]

What is this?

MiPAC currently has no API documentation. So we are thinking of adding documentation using Sphinx.

What is the problem?

Maintaining the documentation is expensive. When a class or module is added, additional files and text must be added, which greatly increases the effort to develop and maintain it. This will probably result in correct documentation at first, but over time, there may be divergence between code and documentation.

What to do

I would like to take a survey here.

1. accept the cost and create the documentation manually, even if some divergence occurs
2. regenerate rst from Python files each time using Sphinx features and GitHubActions etc.

The second option is to use the sphinx-apidoc command in Sphinx to generate rst files from Python files, and use them with GitHubActions to keep them up-to-date. However, there are some problems with this, and it is expected to make translation of the documentation difficult. Also, it will be difficult to manually adjust the documentation.