From abf207b76d483ff907e6ba7eb156e8b0cdd9f589 Mon Sep 17 00:00:00 2001 From: Taras Savchyn Date: Wed, 21 Oct 2020 23:56:08 +0300 Subject: [PATCH 1/8] Implement autosummary patch for autolisting --- docs/source/conf.py | 47 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 47 insertions(+) diff --git a/docs/source/conf.py b/docs/source/conf.py index 0ceb7346bd1c..845b02e4c924 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -205,3 +205,50 @@ # replaces pending_xref node with desc_type for type annotations sphinx.domains.python.type_to_xref = lambda t, e=None: addnodes.desc_type("", nodes.Text(t)) + +# -- Autosummary patch to get list of a classes, funcs automatically ---------- + +from importlib import import_module +from inspect import getmembers, isclass, isfunction +import sphinx.ext.autosummary +from sphinx.ext.autosummary import Autosummary +from docutils.parsers.rst import directives +from docutils.statemachine import StringList + + +class BetterAutosummary(Autosummary): + """Autosummary with autolisting for modules. + + Use :autolist: option to get list of classes an functions for currentmodule. + + Example Usage: + + .. currentmodule:: ignite.metrics + + .. autosummary:: + :toctree: + :nosignatures: + :autolist: + """ + # Add new option + _option_spec = Autosummary.option_spec.copy() + _option_spec.update({'autolist': directives.unchanged}) + option_spec = _option_spec + + def run(self): + if 'autolist' in self.options: + # Get current module name + module_name = (self.env.ref_context.get("py:module")) + # Import module + module = import_module(module_name) + # Get public names + names = getattr(module, "__all__") + # Get list of all classes and functions inside module + names = [name for name in names if (isclass(getattr(module, name)) or isfunction(getattr(module, name)))] + # Update content + self.content = StringList(names) + return super().run() + + +# Patch original Autosummary +sphinx.ext.autosummary.Autosummary = BetterAutosummary From cdbc75635e4957991677fdc126b095afacdd7de5 Mon Sep 17 00:00:00 2001 From: Taras Savchyn Date: Wed, 21 Oct 2020 23:56:31 +0300 Subject: [PATCH 2/8] Fix css for autogenerated tables via autosummary --- docs/source/_templates/_static/css/ignite_theme.css | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/docs/source/_templates/_static/css/ignite_theme.css b/docs/source/_templates/_static/css/ignite_theme.css index a8f145986182..1f267e0474b1 100644 --- a/docs/source/_templates/_static/css/ignite_theme.css +++ b/docs/source/_templates/_static/css/ignite_theme.css @@ -125,3 +125,12 @@ div.container a.header-logo line-height: 1; } +/* automatically generated toctree tables */ + +article.pytorch-article table.longtable.docutils.align-default colgroup { + display: none; +} + +article.pytorch-article table.longtable.docutils.align-default tbody td:first-child { + width: 30%; +} From e62e10a6c573c735291066ff292cbb8817437568 Mon Sep 17 00:00:00 2001 From: Taras Savchyn Date: Thu, 22 Oct 2020 00:41:11 +0300 Subject: [PATCH 3/8] Improve autolist feature --- docs/source/conf.py | 44 ++++++++++++++++++++++++++++++++------------ 1 file changed, 32 insertions(+), 12 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index 845b02e4c924..0f50d1bfcd3d 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -232,21 +232,41 @@ class BetterAutosummary(Autosummary): """ # Add new option _option_spec = Autosummary.option_spec.copy() - _option_spec.update({'autolist': directives.unchanged}) + _option_spec.update({ + "autolist": directives.unchanged, + "autolist-classes": directives.unchanged, + "autolist-functions": directives.unchanged, + }) option_spec = _option_spec def run(self): - if 'autolist' in self.options: - # Get current module name - module_name = (self.env.ref_context.get("py:module")) - # Import module - module = import_module(module_name) - # Get public names - names = getattr(module, "__all__") - # Get list of all classes and functions inside module - names = [name for name in names if (isclass(getattr(module, name)) or isfunction(getattr(module, name)))] - # Update content - self.content = StringList(names) + for auto in ("autolist", "autolist-classes", "autolist-functions"): + if auto in self.options: + # Get current module name + module_name = (self.env.ref_context.get("py:module")) + # Import module + module = import_module(module_name) + # Get public names + names = getattr(module, "__all__") + + if auto == "autolist": + # Get list of all classes and functions inside module + names = [name for name in names if (isclass(getattr(module, name)) or + isfunction(getattr(module, name)))] + else: + if auto == "autolist-classes": + # Get only classes + check = isclass + elif auto == "autolist-functions": + # Get only functions + check = isfunction + else: + raise NotImplementedError + + names = [name for name in names if check(getattr(module, name))] + + # Update content + self.content = StringList(names) return super().run() From 2ce4ddf037da917bbddfe98cf0ee836b5393c717 Mon Sep 17 00:00:00 2001 From: Taras Savchyn Date: Thu, 22 Oct 2020 00:41:58 +0300 Subject: [PATCH 4/8] Add toctrees for methods and classes for ignite --- docs/source/distributed.rst | 15 +++++++++++++++ docs/source/engine.rst | 23 ++++++++++++++++++----- docs/source/exceptions.rst | 5 +++++ docs/source/handlers.rst | 14 +++++--------- docs/source/metrics.rst | 29 +++++------------------------ docs/source/utils.rst | 5 +++++ 6 files changed, 53 insertions(+), 38 deletions(-) diff --git a/docs/source/distributed.rst b/docs/source/distributed.rst index bd4f2303911e..32f47ef87da9 100644 --- a/docs/source/distributed.rst +++ b/docs/source/distributed.rst @@ -61,6 +61,11 @@ ignite.distributed.auto .. currentmodule:: ignite.distributed.auto +.. autosummary:: + :toctree: + :nosignatures: + :autolist: + .. automodule:: ignite.distributed.auto :members: @@ -70,6 +75,11 @@ ignite.distributed.launcher .. currentmodule:: ignite.distributed.launcher +.. autosummary:: + :toctree: + :nosignatures: + :autolist: + .. automodule:: ignite.distributed.launcher :members: @@ -82,6 +92,11 @@ group or spawn multiple processes. .. currentmodule:: ignite.distributed.utils +.. autosummary:: + :toctree: + :nosignatures: + :autolist: + .. automodule:: ignite.distributed.utils :members: diff --git a/docs/source/engine.rst b/docs/source/engine.rst index 807f62b21487..f690bc5cab72 100644 --- a/docs/source/engine.rst +++ b/docs/source/engine.rst @@ -3,15 +3,28 @@ ignite.engine Main module of the library containing: -- :class:`~ignite.engine.engine.Engine` - abstraction that loops provided data, executes a processing function and returns a result -- :class:`~ignite.engine.events.Events` - events triggered by the :class:`~ignite.engine.engine.Engine` during execution -- :class:`~ignite.engine.events.State` - object to pass internal and user-defined data between event handlers +.. currentmodule:: ignite.engine.engine + +.. autosummary:: + :toctree: + :nosignatures: + :autolist: + +.. currentmodule:: ignite.engine.events + +.. autosummary:: + :toctree: + :nosignatures: + :autolist: and helper methods: -- :meth:`~ignite.engine.create_supervised_trainer` - creates single model/optimizer/criterion supervised trainer -- :meth:`~ignite.engine.create_supervised_evaluator` - creates single model supervised evaluation engine +.. currentmodule:: ignite.engine +.. autosummary:: + :toctree: + :nosignatures: + :autolist-functions: More details about those structures can be found in :doc:`concepts`. diff --git a/docs/source/exceptions.rst b/docs/source/exceptions.rst index db84dbde482c..ea4088d30e91 100644 --- a/docs/source/exceptions.rst +++ b/docs/source/exceptions.rst @@ -3,4 +3,9 @@ ignite.exceptions .. currentmodule:: ignite.exceptions +.. autosummary:: + :toctree: + :nosignatures: + :autolist: + .. autoclass:: NotComputableError diff --git a/docs/source/handlers.rst b/docs/source/handlers.rst index 96b18175d4b0..bb667b6d1d51 100644 --- a/docs/source/handlers.rst +++ b/docs/source/handlers.rst @@ -4,17 +4,13 @@ ignite.handlers Complete list of handlers ------------------------- - - :class:`~ignite.handlers.Checkpoint` - - :class:`~ignite.handlers.checkpoint.BaseSaveHandler` - - :class:`~ignite.handlers.DiskSaver` - - :class:`~ignite.handlers.ModelCheckpoint` - - :class:`~ignite.handlers.EarlyStopping` - - :class:`~ignite.handlers.Timer` - - :class:`~ignite.handlers.TerminateOnNan` - - .. currentmodule:: ignite.handlers +.. autosummary:: + :toctree: + :nosignatures: + :autolist: + .. autoclass:: Checkpoint :members: load_objects diff --git a/docs/source/metrics.rst b/docs/source/metrics.rst index 53fa5bead687..a58a5dbde324 100644 --- a/docs/source/metrics.rst +++ b/docs/source/metrics.rst @@ -239,32 +239,13 @@ devices. Therefore, once collected, these internal variables can be used to comp Complete list of metrics ------------------------ - - :class:`~ignite.metrics.Accuracy` - - :class:`~ignite.metrics.Average` - - :class:`~ignite.metrics.ConfusionMatrix` - - :meth:`~ignite.metrics.DiceCoefficient` - - :class:`~ignite.metrics.EpochMetric` - - :meth:`~ignite.metrics.Fbeta` - - :class:`~ignite.metrics.GeometricAverage` - - :meth:`~ignite.metrics.IoU` - - :meth:`~ignite.metrics.mIoU` - - :class:`~ignite.metrics.Loss` - - :class:`~ignite.metrics.MeanAbsoluteError` - - :class:`~ignite.metrics.MeanPairwiseDistance` - - :class:`~ignite.metrics.MeanSquaredError` - - :class:`~ignite.metrics.Metric` - - :class:`~ignite.metrics.MetricsLambda` - - :class:`~ignite.metrics.Precision` - - :class:`~ignite.metrics.Recall` - - :class:`~ignite.metrics.RootMeanSquaredError` - - :class:`~ignite.metrics.RunningAverage` - - :class:`~ignite.metrics.SSIM` - - :class:`~ignite.metrics.TopKCategoricalAccuracy` - - :class:`~ignite.metrics.VariableAccumulation` - - .. currentmodule:: ignite.metrics +.. autosummary:: + :toctree: + :nosignatures: + :autolist: + .. autoclass:: Accuracy .. autoclass:: Average diff --git a/docs/source/utils.rst b/docs/source/utils.rst index 9be48ed37ebc..2c5ac3a6c641 100644 --- a/docs/source/utils.rst +++ b/docs/source/utils.rst @@ -5,5 +5,10 @@ Module with helper methods .. currentmodule:: ignite.utils +.. autosummary:: + :toctree: + :nosignatures: + :autolist: + .. automodule:: ignite.utils :members: From d66a0536b73a9269430f8db4c608a5fd80349516 Mon Sep 17 00:00:00 2001 From: Taras Savchyn Date: Thu, 22 Oct 2020 01:30:31 +0300 Subject: [PATCH 5/8] Better import for autolist --- docs/source/conf.py | 51 +++++++++++++++++++++++++++++++++++---------- 1 file changed, 40 insertions(+), 11 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index 0f50d1bfcd3d..cc692da26ac7 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -219,7 +219,13 @@ class BetterAutosummary(Autosummary): """Autosummary with autolisting for modules. - Use :autolist: option to get list of classes an functions for currentmodule. + By default it tries to import all public names (__all__), + otherwise import all classes and/or functions in a module. + + Options: + - :autolist: option to get list of classes and functions from currentmodule. + - :autolist-classes: option to get list of classes from currentmodule. + - :autolist-functions: option to get list of functions from currentmodule. Example Usage: @@ -230,29 +236,52 @@ class BetterAutosummary(Autosummary): :nosignatures: :autolist: """ + # Add new option _option_spec = Autosummary.option_spec.copy() - _option_spec.update({ - "autolist": directives.unchanged, - "autolist-classes": directives.unchanged, - "autolist-functions": directives.unchanged, - }) + _option_spec.update( + { + "autolist": directives.unchanged, + "autolist-classes": directives.unchanged, + "autolist-functions": directives.unchanged, + } + ) option_spec = _option_spec def run(self): for auto in ("autolist", "autolist-classes", "autolist-functions"): if auto in self.options: # Get current module name - module_name = (self.env.ref_context.get("py:module")) + module_name = self.env.ref_context.get("py:module") # Import module module = import_module(module_name) - # Get public names - names = getattr(module, "__all__") + + # Get public names (if possible) + try: + names = getattr(module, "__all__") + except AttributeError: + # Get classes defined in the module + cls_names = [ + name[0] + for name in getmembers(module, isclass) + if name[-1].__module__ == module_name and not (name[0].startswith("_")) + ] + # Get functions defined in the module + fn_names = [ + name[0] + for name in getmembers(module, isfunction) + if (name[-1].__module__ == module_name) and not (name[0].startswith("_")) + ] + names = cls_names + fn_names + # It may happen that module doesn't have any defined class or func + if not names: + names = [name[0] for name in getmembers(module)] if auto == "autolist": # Get list of all classes and functions inside module - names = [name for name in names if (isclass(getattr(module, name)) or - isfunction(getattr(module, name)))] + names = [ + name for name in names if (isclass(getattr(module, name)) or isfunction(getattr(module, name))) + ] else: if auto == "autolist-classes": # Get only classes From 86bf4144e7a6212b343fc596aae9001e15b52da2 Mon Sep 17 00:00:00 2001 From: Taras Savchyn Date: Thu, 22 Oct 2020 01:53:44 +0300 Subject: [PATCH 6/8] Add toctrees for methods and classes for contrib package --- docs/source/contrib/engines.rst | 13 ++++++ docs/source/contrib/handlers.rst | 77 ++++++++++++++++++++++++++++++++ docs/source/contrib/metrics.rst | 26 +++++------ 3 files changed, 101 insertions(+), 15 deletions(-) diff --git a/docs/source/contrib/engines.rst b/docs/source/contrib/engines.rst index 3a60d6ac81df..563c2d368690 100644 --- a/docs/source/contrib/engines.rst +++ b/docs/source/contrib/engines.rst @@ -5,6 +5,19 @@ Contribution module of engines and helper tools .. currentmodule:: ignite.contrib.engines +.. currentmodule:: ignite.contrib.engines.tbptt + +.. autosummary:: + :toctree: + :nosignatures: + :autolist: + +.. currentmodule:: ignite.contrib.engines.common + +.. autosummary:: + :toctree: + :nosignatures: + :autolist: Truncated Backpropagation Throught Time --------------------------------------- diff --git a/docs/source/contrib/handlers.rst b/docs/source/contrib/handlers.rst index a36b51cb2507..f066956e3706 100644 --- a/docs/source/contrib/handlers.rst +++ b/docs/source/contrib/handlers.rst @@ -7,12 +7,27 @@ Contribution module of handlers param_scheduler --------------- +.. currentmodule:: ignite.contrib.handlers.param_scheduler + +.. autosummary:: + :toctree: + :nosignatures: + :autolist: + .. automodule:: ignite.contrib.handlers.param_scheduler :members: + lr_finder --------- +.. currentmodule:: ignite.contrib.handlers.lr_finder + +.. autosummary:: + :toctree: + :nosignatures: + :autolist: + .. automodule:: ignite.contrib.handlers.lr_finder :members: @@ -20,15 +35,30 @@ lr_finder time_profilers --------------- +.. currentmodule:: ignite.contrib.handlers.time_profilers + +.. autosummary:: + :toctree: + :nosignatures: + :autolist: + + .. automodule:: ignite.contrib.handlers.time_profilers :members: + tensorboard_logger ------------------ See `tensorboardX mnist example `_ and `CycleGAN and EfficientNet notebooks `_ for detailed usage. +.. currentmodule:: ignite.contrib.handlers.tensorboard_logger + +.. autosummary:: + :toctree: + :nosignatures: + :autolist: .. automodule:: ignite.contrib.handlers.tensorboard_logger :members: @@ -41,6 +71,13 @@ visdom_logger See `visdom mnist example `_ for detailed usage. +.. currentmodule:: ignite.contrib.handlers.visdom_logger + +.. autosummary:: + :toctree: + :nosignatures: + :autolist: + .. automodule:: ignite.contrib.handlers.visdom_logger :members: :inherited-members: @@ -52,6 +89,12 @@ neptune_logger See `neptune mnist example `_ for detailed usage. +.. currentmodule:: ignite.contrib.handlers.neptune_logger + +.. autosummary:: + :toctree: + :nosignatures: + :autolist: .. automodule:: ignite.contrib.handlers.neptune_logger :members: @@ -61,6 +104,13 @@ for detailed usage. mlflow_logger ------------- +.. currentmodule:: ignite.contrib.handlers.mlflow_logger + +.. autosummary:: + :toctree: + :nosignatures: + :autolist: + .. automodule:: ignite.contrib.handlers.mlflow_logger :members: :inherited-members: @@ -72,6 +122,12 @@ tqdm_logger See `tqdm mnist example `_ for detailed usage. +.. currentmodule:: ignite.contrib.handlers.tqdm_logger + +.. autosummary:: + :toctree: + :nosignatures: + :autolist: .. automodule:: ignite.contrib.handlers.tqdm_logger :members: @@ -79,6 +135,13 @@ for detailed usage. polyaxon_logger --------------- +.. currentmodule:: ignite.contrib.handlers.polyaxon_logger + +.. autosummary:: + :toctree: + :nosignatures: + :autolist: + .. automodule:: ignite.contrib.handlers.polyaxon_logger :members: :inherited-members: @@ -89,6 +152,13 @@ wandb_logger See `wandb mnist example `_ for detailed usage. +.. currentmodule:: ignite.contrib.handlers.wandb_logger + +.. autosummary:: + :toctree: + :nosignatures: + :autolist: + .. automodule:: ignite.contrib.handlers.wandb_logger :members: :inherited-members: @@ -99,6 +169,13 @@ trains_logger See `trains mnist example `_ for detailed usage. +.. currentmodule:: ignite.contrib.handlers.trains_logger + +.. autosummary:: + :toctree: + :nosignatures: + :autolist: + .. automodule:: ignite.contrib.handlers.trains_logger :members: :inherited-members: diff --git a/docs/source/contrib/metrics.rst b/docs/source/contrib/metrics.rst index 01f8a1083cda..687496e38160 100644 --- a/docs/source/contrib/metrics.rst +++ b/docs/source/contrib/metrics.rst @@ -5,6 +5,11 @@ Contribution module of metrics .. currentmodule:: ignite.contrib.metrics +.. autosummary:: + :toctree: + :nosignatures: + :autolist: + .. automodule:: ignite.contrib.metrics :members: :imported-members: @@ -26,21 +31,12 @@ metrics useful for regression tasks. Definitions of metrics are based on `Botchk Complete list of metrics: - - :class:`~ignite.contrib.metrics.regression.CanberraMetric` - - :class:`~ignite.contrib.metrics.regression.FractionalAbsoluteError` - - :class:`~ignite.contrib.metrics.regression.FractionalBias` - - :class:`~ignite.contrib.metrics.regression.GeometricMeanAbsoluteError` - - :class:`~ignite.contrib.metrics.regression.GeometricMeanRelativeAbsoluteError` - - :class:`~ignite.contrib.metrics.regression.ManhattanDistance` - - :class:`~ignite.contrib.metrics.regression.MaximumAbsoluteError` - - :class:`~ignite.contrib.metrics.regression.MeanAbsoluteRelativeError` - - :class:`~ignite.contrib.metrics.regression.MeanError` - - :class:`~ignite.contrib.metrics.regression.MeanNormalizedBias` - - :class:`~ignite.contrib.metrics.regression.MedianAbsoluteError` - - :class:`~ignite.contrib.metrics.regression.MedianAbsolutePercentageError` - - :class:`~ignite.contrib.metrics.regression.MedianRelativeAbsoluteError` - - :class:`~ignite.contrib.metrics.regression.R2Score` - - :class:`~ignite.contrib.metrics.regression.WaveHedgesDistance` +.. currentmodule:: ignite.contrib.metrics.regression + +.. autosummary:: + :toctree: + :nosignatures: + :autolist: .. autoclass:: CanberraMetric From 95217773c2a021124539b8b6f44e63182037c597 Mon Sep 17 00:00:00 2001 From: Taras Savchyn Date: Fri, 23 Oct 2020 01:17:02 +0300 Subject: [PATCH 7/8] Fix CSS for autosummary table row height --- docs/source/_templates/_static/css/ignite_theme.css | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/docs/source/_templates/_static/css/ignite_theme.css b/docs/source/_templates/_static/css/ignite_theme.css index 1f267e0474b1..0eadd338bd27 100644 --- a/docs/source/_templates/_static/css/ignite_theme.css +++ b/docs/source/_templates/_static/css/ignite_theme.css @@ -134,3 +134,12 @@ article.pytorch-article table.longtable.docutils.align-default colgroup { article.pytorch-article table.longtable.docutils.align-default tbody td:first-child { width: 30%; } + +article.pytorch-article table.longtable.docutils.align-default tbody td { + padding: 0.25rem; +} + +article.pytorch-article table.longtable.docutils.align-default tbody td p { + margin-block-start: 0.1em; + margin-block-end: 0.1em; +} From 8adcc8655fe84f84f1b837391810b110f16dc668 Mon Sep 17 00:00:00 2001 From: Taras Savchyn Date: Fri, 23 Oct 2020 02:29:41 +0300 Subject: [PATCH 8/8] Fix warnings raised by toctree --- docs/source/conf.py | 1 - docs/source/contrib/engines.rst | 2 -- docs/source/contrib/handlers.rst | 11 ----------- docs/source/contrib/metrics.rst | 2 -- docs/source/distributed.rst | 3 --- docs/source/engine.rst | 3 --- docs/source/exceptions.rst | 1 - docs/source/handlers.rst | 1 - docs/source/metrics.rst | 1 - docs/source/utils.rst | 1 - 10 files changed, 26 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index cc692da26ac7..2374cd4a4495 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -232,7 +232,6 @@ class BetterAutosummary(Autosummary): .. currentmodule:: ignite.metrics .. autosummary:: - :toctree: :nosignatures: :autolist: """ diff --git a/docs/source/contrib/engines.rst b/docs/source/contrib/engines.rst index 563c2d368690..e223e17035a6 100644 --- a/docs/source/contrib/engines.rst +++ b/docs/source/contrib/engines.rst @@ -8,14 +8,12 @@ Contribution module of engines and helper tools .. currentmodule:: ignite.contrib.engines.tbptt .. autosummary:: - :toctree: :nosignatures: :autolist: .. currentmodule:: ignite.contrib.engines.common .. autosummary:: - :toctree: :nosignatures: :autolist: diff --git a/docs/source/contrib/handlers.rst b/docs/source/contrib/handlers.rst index f066956e3706..9d1d16c3ae3e 100644 --- a/docs/source/contrib/handlers.rst +++ b/docs/source/contrib/handlers.rst @@ -10,7 +10,6 @@ param_scheduler .. currentmodule:: ignite.contrib.handlers.param_scheduler .. autosummary:: - :toctree: :nosignatures: :autolist: @@ -24,7 +23,6 @@ lr_finder .. currentmodule:: ignite.contrib.handlers.lr_finder .. autosummary:: - :toctree: :nosignatures: :autolist: @@ -38,7 +36,6 @@ time_profilers .. currentmodule:: ignite.contrib.handlers.time_profilers .. autosummary:: - :toctree: :nosignatures: :autolist: @@ -56,7 +53,6 @@ and `CycleGAN and EfficientNet notebooks