Generalize the use of links to the theory documentation from the API one

mdelozzo commented 2 years ago

Hello,

And thank you very much for your great library! My first contribution will not be a proposal of functionality but a remark on the documentation.

In the theory documentation, the pages propose links to the corresponding API documentation but unfortunately the opposite is not always true. Moreover, it is not easy to guess the path to the page of a documentation corresponding to the page of the other documentation as their tables of contents are not mirrors of each other (theory TOC / API TOC)

Being able to move easily from theory to API and from API to theory is really a good thing and I think it should be generalized.

Additional remark: the theory related to some mathematica objects is available in API pages but is missing in the theory documentation. It can sometimes be confusing to discover concepts, algorithms, ... in the API. Why not put all the theory materials in the theory documentation and use reminder in some API pages if necessary?

Some examples:

the theory documentation of copulas refers to the API of the available copulas but the API of the normal copula does not refer to the theory of copulas. Furthermore, the theory of normal copula is documented in a Notes section of the API page but no information can be found about the normal copula in the theory documentation.
the theory documentation of Kriging refers to the API documentation of Kriging and vice versa.
the theory documentation of HSIC refers to the API documentation but the opposite is false.

mbaudin47 commented 1 year ago

Thank you very much for this issue! We analyze your examples and have a suggestion to improve the current state. We noticed that the way that current API help pages present links to the theory help page is somewhat inconsistent. For example, see the "Refer to" in the following help page FittingTest.AIC:

In the theory document of Kriging, we see links from the theory to the API and examples:

Would you agree that a good practice would be to include a new category within API help pages, e.g.:

Theory:
     - Link 1
     - Link 2

We identified two different tasks on this topic:

[ ] : implement a new "standard" way to present a link to the API help page, using a new "Theory" standardized section.
[ ] : identify all current help pages which need to be updated.

Here is a short list of help pages to update:

In order to update these pages, we may search for "Refer to" and select the pages which have to be updated.

mdelozzo commented 1 year ago

Yes, I would. Your proposal seems to be a good improvement. Thanks!

openturns / openturns

Generalize the use of links to the theory documentation from the API one #2114