Repository: scipy/scipy

Issue:
DOC: Should `Result Classes` be its own top level section?
### Issue with current documentation:

Currently the SciPy documentation for version 1.10 shows [Result Classes](https://docs.scipy.org/doc/scipy/reference/stats._result_classes.html) as its own, top level, section. I don't believe this is correct, as they are only results for stats. Should this come under scipy.stats.result_classes?




### Idea or request for content:

Move results classes to scipy.stats.result_classes

### Additional context (e.g. screenshots, GIFs)

 ![SciPy Result Classes in wrong position](https://user-images.githubusercontent.com/30074037/214999095-cbf05cbd-628f-4aff-8dfc-6e22c507f3b9.png)


Discussion:
It has been like that for a few versions, but when I fight with Sphinx, Sphinx usually wins.

Ideally, it would not show up in the table of contents at all. These are classes that we want to be linked from the corresponding functions; e.g. in `scipy.stats.contingency.relative_risk`:

![image](https://user-images.githubusercontent.com/6570539/214999971-3a237651-944b-46b8-8137-fa3738fdba12.png)

But these are not importable or intended to be used.

```python3
from scipy.stats import RelativeRiskResult  # should raise ImportError
# ImportError: cannot import name 'FitResult' from 'scipy.stats' (C:\Users\matth\scipy\scipy\stats\__init__.py)
```

So ideally, they would not appear anywhere except via links from the functions that use them. IIRC the problem has been that Sphinx will not render the pages unless they are included in a table of contents somewhere.

See history in gh-13048, gh-13462, gh-15923
Ok. Thanks for the explanation. I'm going to leave this open and, if someone comes along who wants to take a crack at it, great.
Well, if you can't completely fix it, would you move it to the very bottom of the main stats page? That way it is at least less visible.
I can try, although I have very little experience with Sphinx so I'm not sure how far I'll get. 
If you can build docs locally, you're already way ahead of me. I'd suggest trying to move that section out of wherever it is and list the items individually in https://github.com/scipy/scipy/blob/main/scipy/stats/__init__.py . The hope is that each of the classes will show up individually at the bottom of the stats page (i.e. below the Warnings / Errors) but "Result Classes" would no longer show up in the side panel. You could include a note that the classes are not importable and they are documented only because instances are returned by other functions.
> You could include a note that the classes are not importable and they are documented only because instances are returned by other functions.

This is a very important point to make as not common in other libraries. Normally all specific exceptions or other return objects are also part of the public API. So as we go another way it needs to be documented.

About the toc, there are other elements I would remove from there as well, we have too many things in the sidebar ATM.
@tupui I've tried to remove it but haven't gotten very far. I've been able to delete the file and build the documentation which leads to the following warnings:

```
checking consistency... /home/kai/Projects/SciPy/kai/scipy/doc/source/reference/generated/scipy.stats._result_classes.BinomTestResult.rst: WARNING: document isn't included in any toctree
/home/kai/Projects/SciPy/kai/scipy/doc/source/reference/generated/scipy.stats._result_classes.FitResult.rst: WARNING: document isn't included in any toctree
/home/kai/Projects/SciPy/kai/scipy/doc/source/reference/generated/scipy.stats._result_classes.OddsRatioResult.rst: WARNING: document isn't included in any toctree
/home/kai/Projects/SciPy/kai/scipy/doc/source/reference/generated/scipy.stats._result_classes.PearsonRResult.rst: WARNING: document isn't included in any toctree
/home/kai/Projects/SciPy/kai/scipy/doc/source/reference/generated/scipy.stats._result_classes.RelativeRiskResult.rst: WARNING: document isn't included in any toctree
/home/kai/Projects/SciPy/kai/scipy/doc/source/reference/generated/scipy.stats._result_classes.TtestResult.rst: WARNING: document isn't included in any toctree
/home/kai/Projects/SciPy/kai/scipy/doc/source/reference/generated/scipy.stats._result_classes.TukeyHSDResult.rst: WARNING: document isn't included in any toctree
done
preparing documents... done
/home/kai/Projects/SciPy/kai/scipy/doc/source/reference/stats.rst:6: WARNING: toctree contains reference to nonexisting document 'reference/stats._result_classes'
/home/kai/Projects/SciPy/kai/scipy/doc/source/reference/stats.rst:6: WARNING: toctree contains reference to nonexisting document 'reference/stats._result_classes'
/home/kai/Projects/SciPy/kai/scipy/doc/source/reference/stats.rst:6: WARNING: toctree contains reference to nonexisting document 'reference/stats._result_classes'                     
/home/kai/Projects/SciPy/kai/scipy/doc/source/reference/stats.rst:6: WARNING: toctree contains reference to nonexisting document 'reference/stats._result_classes'
/home/kai/Projects/SciPy/kai/scipy/doc/source/reference/stats.rst:6: WARNING: toctree contains reference to nonexisting document 'reference/stats._result_classes'                     
/home/kai/Projects/SciPy/kai/scipy/doc/source/reference/stats.rst:6: WARNING: toctree contains reference to nonexisting document 'reference/stats._result_classes'
```

Any idea of where to go from here?
Thanks Kai. So yeah every document needs to be present in a toctree. What you need to do is to have a hidden tree. Basically on an existing tree you can add `:hidden:` (you should have some examples in our doc to see how tu use this). And it will not be included, but still there for Sphinx.
It looks like it's already hidden but being ignored:

https://github.com/scipy/scipy/blob/main/doc/source/reference/stats.rst
ok so you are saying you removed the file `stats._result_classes.rst` and you got the warnings?

Did you clean your doc build tree? I would start here as the generated folder would have old refs.

Resolving patch:
diff --git a/scipy/signal/_signaltools.py b/scipy/signal/_signaltools.py
--- a/scipy/signal/_signaltools.py
+++ b/scipy/signal/_signaltools.py
@@ -4108,11 +4108,11 @@ def filtfilt(b, a, x, axis=-1, padtype='odd', padlen=None, method='pad',
     argument.  The difference between `y1` and `y2` is small.  For long
     signals, using `irlen` gives a significant performance improvement.
 
-    >>> x = rng.standard_normal(5000)
+    >>> x = rng.standard_normal(4000)
     >>> y1 = signal.filtfilt(b, a, x, method='gust')
     >>> y2 = signal.filtfilt(b, a, x, method='gust', irlen=approx_impulse_len)
     >>> print(np.max(np.abs(y1 - y2)))
-    1.80056858312e-10
+    2.875334415008979e-10
 
     """
     b = np.atleast_1d(b)
diff --git a/scipy/stats/__init__.py b/scipy/stats/__init__.py
--- a/scipy/stats/__init__.py
+++ b/scipy/stats/__init__.py
@@ -569,6 +569,20 @@
    NearConstantInputWarning
    FitError
 
+Result classes used in :mod:`scipy.stats`
+-----------------------------------------
+
+.. warning::
+
+    These classes are private, but they are included here because instances
+    of them are returned by other statistical functions. User import and
+    instantiation is not supported.
+
+.. toctree::
+   :maxdepth: 2
+
+   stats._result_classes
+
 """
 
 from ._warnings_errors import (ConstantInputWarning, NearConstantInputWarning,


Test patch: