Extend docs (#1309)

* re-structure manual and use 'collapse'

* ADD link to auto-sklearn-talks

* unifying titles

* Clarify default memory and cpu usage

* FIX sphinx_gallery to <=0.10.0

0.10.1 would raise an error for '-D plot_gallery=0'

* Re-structure faq

* FIX comments by mfeurer

* boldface items

* merge manual into FAQ

* FIX minor

* FIX typo

* Update doc/faq.rst

Co-authored-by: Eddie Bergman <[email protected]>

* Update doc/faq.rst

Co-authored-by: Eddie Bergman <[email protected]>

* Update doc/faq.rst

Co-authored-by: Eddie Bergman <[email protected]>

* Update doc/faq.rst

Co-authored-by: Eddie Bergman <[email protected]>

* Update doc/manual.rst

Co-authored-by: Eddie Bergman <[email protected]>

* Update doc/manual.rst

Co-authored-by: Eddie Bergman <[email protected]>

* Update doc/faq.rst

Co-authored-by: Eddie Bergman <[email protected]>

* FIX link

Co-authored-by: Eddie Bergman <[email protected]>

Author: KEggensperger

autosklearn/estimators.py

@@ -76,7 +76,7 @@ def __init__(
         ensemble_size : int, optional (default=50)
             Number of models added to the ensemble built by *Ensemble
             selection from libraries of models*. Models are drawn with
-            replacement.
+            replacement. If set to ``0`` no ensemble is fit.
 
         ensemble_nbest : int, optional (default=50)
             Only consider the ``ensemble_nbest`` models when building an
@@ -96,10 +96,14 @@ def __init__(
         memory_limit : int, optional (3072)
             Memory limit in MB for the machine learning algorithm.
             `auto-sklearn` will stop fitting the machine learning algorithm if
-            it tries to allocate more than `memory_limit` MB.
-            If None is provided, no memory limit is set.
-            In case of multi-processing, `memory_limit` will be per job.
-            This memory limit also applies to the ensemble creation process.
+            it tries to allocate more than ``memory_limit`` MB.
+            
+            **Important notes:** 
+            
+            * If ``None`` is provided, no memory limit is set.
+            * In case of multi-processing, ``memory_limit`` will be *per job*, so the total usage is 
+              ``n_jobs x memory_limit``.
+            * The memory limit also applies to the ensemble creation process.
 
         include : dict, optional (None)
             If None, all possible algorithms are used. Otherwise specifies
@@ -145,10 +149,10 @@ def __init__(
             * 'cv-iterative-fit': {'folds': int}
             * 'partial-cv': {'folds': int, 'shuffle': bool}
             * BaseCrossValidator or _RepeatedSplits or BaseShuffleSplit object: all arguments
-                required by chosen class as specified in scikit-learn documentation.
-                If arguments are not provided, scikit-learn defaults are used.
-                If no defaults are available, an exception is raised.
-                Refer to the 'n_splits' argument as 'folds'.
+              required by chosen class as specified in scikit-learn documentation.
+              If arguments are not provided, scikit-learn defaults are used.
+              If no defaults are available, an exception is raised.
+              Refer to the 'n_splits' argument as 'folds'.
 
         tmp_folder : string, optional (None)
             folder to store configuration output and log files, if ``None``
@@ -160,13 +164,15 @@ def __init__(
 
         n_jobs : int, optional, experimental
             The number of jobs to run in parallel for ``fit()``. ``-1`` means
-            using all processors. By default, Auto-sklearn uses a single core
-            for fitting the machine learning model and a single core for fitting
-            an ensemble. Ensemble building is not affected by ``n_jobs`` but
-            can be controlled by the number of models in the ensemble. In
-            contrast to most scikit-learn models, ``n_jobs`` given in the
-            constructor is not applied to the ``predict()`` method. If
-            ``dask_client`` is None, a new dask client is created.
+            using all processors. 
+            
+            **Important notes**: 
+            
+            * By default, Auto-sklearn uses one core. 
+            * Ensemble building is not affected by ``n_jobs`` but can be controlled by the number 
+              of models in the ensemble.
+            * ``predict()`` is not affected by ``n_jobs`` (in contrast to most scikit-learn models)
+            * If ``dask_client`` is ``None``, a new dask client is created.
 
         dask_client : dask.distributed.Client, optional
             User-created dask client, can be used to start a dask cluster and then
@@ -182,7 +188,7 @@ def __init__(
             * ``'y_optimization'`` : do not save the predictions for the
               optimization/validation set, which would later on be used to build
               an ensemble.
-            * ``'model'`` : do not save any model files
+            * ``model`` : do not save any model files
 
         smac_scenario_args : dict, optional (None)
             Additional arguments inserted into the scenario of SMAC. See the
@@ -559,7 +565,7 @@ def leaderboard(
         Gives an overview of all models trained during the search process along
         with various statistics about their training.
 
-        The availble statistics are:
+        The available statistics are:
 
         **Simple**:
 

autosklearn/experimental/askl2.py

@@ -218,7 +218,7 @@ def __init__(
         ensemble_size : int, optional (default=50)
             Number of models added to the ensemble built by *Ensemble
             selection from libraries of models*. Models are drawn with
-            replacement.
+            replacement. If set to ``0`` no ensemble is fit.
 
         ensemble_nbest : int, optional (default=50)
             Only consider the ``ensemble_nbest`` models when building an
@@ -238,10 +238,14 @@ def __init__(
         memory_limit : int, optional (3072)
             Memory limit in MB for the machine learning algorithm.
             `auto-sklearn` will stop fitting the machine learning algorithm if
-            it tries to allocate more than `memory_limit` MB.
-            If None is provided, no memory limit is set.
-            In case of multi-processing, `memory_limit` will be per job.
-            This memory limit also applies to the ensemble creation process.
+            it tries to allocate more than ``memory_limit`` MB.
+            
+            **Important notes:** 
+            
+            * If ``None`` is provided, no memory limit is set.
+            * In case of multi-processing, ``memory_limit`` will be *per job*, so the total usage is 
+              ``n_jobs x memory_limit``.
+            * The memory limit also applies to the ensemble creation process.
 
         tmp_folder : string, optional (None)
             folder to store configuration output and log files, if ``None``
@@ -253,13 +257,15 @@ def __init__(
 
         n_jobs : int, optional, experimental
             The number of jobs to run in parallel for ``fit()``. ``-1`` means
-            using all processors. By default, Auto-sklearn uses a single core
-            for fitting the machine learning model and a single core for fitting
-            an ensemble. Ensemble building is not affected by ``n_jobs`` but
-            can be controlled by the number of models in the ensemble. In
-            contrast to most scikit-learn models, ``n_jobs`` given in the
-            constructor is not applied to the ``predict()`` method. If
-            ``dask_client`` is None, a new dask client is created.
+            using all processors. 
+            
+            **Important notes**: 
+            
+            * By default, Auto-sklearn uses one core. 
+            * Ensemble building is not affected by ``n_jobs`` but can be controlled by the number 
+              of models in the ensemble.
+            * ``predict()`` is not affected by ``n_jobs`` (in contrast to most scikit-learn models)
+            * If ``dask_client`` is ``None``, a new dask client is created.
 
         dask_client : dask.distributed.Client, optional
             User-created dask client, can be used to start a dask cluster and then
@@ -275,7 +281,7 @@ def __init__(
             * ``'y_optimization'`` : do not save the predictions for the
               optimization/validation set, which would later on be used to build
               an ensemble.
-            * ``'model'`` : do not save any model files
+            * ``model`` : do not save any model files
 
         smac_scenario_args : dict, optional (None)
             Additional arguments inserted into the scenario of SMAC. See the

doc/conf.py

@@ -43,6 +43,7 @@
               'sphinx.ext.doctest', 'sphinx.ext.coverage',
               'sphinx.ext.mathjax', 'sphinx.ext.viewcode',
               'sphinx_gallery.gen_gallery', 'sphinx.ext.autosectionlabel',
+              'sphinx_toolbox.collapse',
               # sphinx.ext.autosexctionlabel raises duplicate label warnings
               # because same section headers are used multiple times throughout
               # the documentation.
@@ -180,7 +181,7 @@
         ('Start', 'index'),
         ('Releases', 'releases'),
         ('Installation', 'installation'),
-        ('Manual', 'manual'),
+        #('Manual', 'manual'),
         ('Examples', 'examples/index'),
         ('API', 'api'),
         ('Extending', 'extending'),