docs: use autosummary generated docs, add nitpicky mode (#1780)

* heading 2 * add headings * test -n mode * autopep8 fix * add nitpicky mode, fix math eq renders, katex pin at 0.13.0 * autopep8 fix * fix flake8, mypy * nitpick ignore ellipsis * rm docstring in empty cuda cache Co-authored-by: ydcjeff <[email protected]>
pytorch · Mar 13, 2021 · bd4ea89 · bd4ea89
1 parent df3ae8e
commit bd4ea89
Show file tree

Hide file tree

Showing 43 changed files with 488 additions and 428 deletions.
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -17,7 +17,7 @@ jobs:
         with:
           python-version: 3.7
 
-      - run: sudo npm install katex@latest -g
+      - run: sudo npm install katex@0.13.0 -g
       - uses: actions/cache@v2
         with:
           path: ~/.cache/pip

diff --git a/.gitignore b/.gitignore
@@ -38,3 +38,4 @@ coverage.xml
 # Documentation
 /docs/src/
 /docs/build/
+/docs/source/generated/
diff --git a/docs/source/_templates/autosummary/class.rst b/docs/source/_templates/autosummary/class.rst
@@ -0,0 +1,20 @@
+{{ objname | escape | underline }}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+   :members:
+
+   {% block methods %}
+   {% if methods %}
+   .. rubric:: {{ _('Methods') }}
+
+   .. autosummary::
+      :nosignatures:
+   {% for item in methods %}
+   {% if item != "__init__" and item not in inherited_members %}
+      ~{{ name }}.{{ item }}
+   {% endif %}
+   {% endfor %}
+   {% endif %}
+   {% endblock %}
diff --git a/docs/source/_templates/autosummary/function.rst b/docs/source/_templates/autosummary/function.rst
@@ -0,0 +1,5 @@
+{{ objname | escape | underline }}
+
+.. currentmodule:: {{ module }}
+
+.. autofunction:: {{ objname }}
diff --git a/docs/source/_templates/autosummary/module.rst b/docs/source/_templates/autosummary/module.rst
@@ -0,0 +1,65 @@
+{{ name | escape | underline }}
+
+.. automodule:: {{ fullname }}
+   :members:
+
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: {{ _('Module Attributes') }}
+
+   .. autosummary::
+      :nosignatures:
+   {% for item in attributes %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block functions %}
+   {% if functions %}
+   .. rubric:: {{ _('Functions') }}
+
+   .. autosummary::
+      :nosignatures:
+   {% for item in functions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block classes %}
+   {% if classes %}
+   .. rubric:: {{ _('Classes') }}
+
+   .. autosummary::
+      :nosignatures:
+   {% for item in classes %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block exceptions %}
+   {% if exceptions %}
+   .. rubric:: {{ _('Exceptions') }}
+
+   .. autosummary::
+      :nosignatures:
+   {% for item in exceptions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+{% block modules %}
+{% if modules %}
+.. rubric:: Modules
+
+.. autosummary::
+   :toctree:
+   :recursive:
+{% for item in modules %}
+   {{ item }}
+{%- endfor %}
+{% endif %}
+{% endblock %}
diff --git a/docs/source/_templates/classwithcall.rst b/docs/source/_templates/classwithcall.rst
@@ -0,0 +1,23 @@
+{{ objname | escape | underline }}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+   :members:
+   :special-members: __call__
+
+   {% block methods %}
+   {% if methods %}
+   .. rubric:: {{ _('Methods') }}
+
+   .. autosummary::
+      :nosignatures:
+
+      ~{{ name }}.__call__
+   {% for item in methods %}
+   {% if item != "__init__" and item not in inherited_members %}
+      ~{{ name }}.{{ item }}
+   {% endif %}
+   {% endfor %}
+   {% endif %}
+   {% endblock %}
diff --git a/docs/source/_templates/fonts.html b/docs/source/_templates/fonts.html
@@ -0,0 +1,24 @@
+<!-- katex links / this needs to be loaded before fonts.html -->
+
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/dist/katex.min.css" crossorigin="anonymous">
+<script async src="https://cdn.jsdelivr.net/npm/[email protected]/dist/katex.min.js" crossorigin="anonymous"></script>
+
+<!-- Preload the theme fonts -->
+
+<link rel="preload" href="{{ pathto('_static/fonts/FreightSans/freight-sans-book.woff2', 1) }}" as="font" type="font/woff2" crossorigin="anonymous">
+<link rel="preload" href="{{ pathto('_static/fonts/FreightSans/freight-sans-medium.woff2', 1) }}" as="font" type="font/woff2" crossorigin="anonymous">
+<link rel="preload" href="{{ pathto('_static/fonts/IBMPlexMono/IBMPlexMono-Medium.woff2', 1) }}" as="font" type="font/woff2" crossorigin="anonymous">
+<link rel="preload" href="{{ pathto('_static/fonts/FreightSans/freight-sans-bold.woff2', 1) }}" as="font" type="font/woff2" crossorigin="anonymous">
+<link rel="preload" href="{{ pathto('_static/fonts/FreightSans/freight-sans-medium-italic.woff2', 1) }}" as="font" type="font/woff2" crossorigin="anonymous">
+<link rel="preload" href="{{ pathto('_static/fonts/IBMPlexMono/IBMPlexMono-SemiBold.woff2', 1) }}" as="font" type="font/woff2" crossorigin="anonymous">
+
+<!-- Preload the katex fonts -->
+
+<link rel="preload" href="https://cdn.jsdelivr.net/npm/[email protected]/dist/fonts/KaTeX_Math-Italic.woff2" as="font" type="font/woff2" crossorigin="anonymous">
+<link rel="preload" href="https://cdn.jsdelivr.net/npm/[email protected]/dist/fonts/KaTeX_Main-Regular.woff2" as="font" type="font/woff2" crossorigin="anonymous">
+<link rel="preload" href="https://cdn.jsdelivr.net/npm/[email protected]/dist/fonts/KaTeX_Main-Bold.woff2" as="font" type="font/woff2" crossorigin="anonymous">
+<link rel="preload" href="https://cdn.jsdelivr.net/npm/[email protected]/dist/fonts/KaTeX_Size1-Regular.woff2" as="font" type="font/woff2" crossorigin="anonymous">
+<link rel="preload" href="https://cdn.jsdelivr.net/npm/[email protected]/dist/fonts/KaTeX_Size4-Regular.woff2" as="font" type="font/woff2" crossorigin="anonymous">
+<link rel="preload" href="https://cdn.jsdelivr.net/npm/[email protected]/dist/fonts/KaTeX_Size2-Regular.woff2" as="font" type="font/woff2" crossorigin="anonymous">
+<link rel="preload" href="https://cdn.jsdelivr.net/npm/[email protected]/dist/fonts/KaTeX_Size3-Regular.woff2" as="font" type="font/woff2" crossorigin="anonymous">
+<link rel="preload" href="https://cdn.jsdelivr.net/npm/[email protected]/dist/fonts/KaTeX_Caligraphic-Regular.woff2" as="font" type="font/woff2" crossorigin="anonymous">
diff --git a/docs/source/_templates/layout.html b/docs/source/_templates/layout.html
@@ -77,17 +77,6 @@
   {%- endblock %}
   {%- block extrahead %} {% endblock %}
 
-  {# Keep modernizr in head - http://modernizr.com/docs/#installing #}
-  <script src="{{ pathto('_static/js/modernizr.min.js', 1) }}"></script>
-
-  <!-- katex links / this needs to be loaded before fonts.html -->
-  <link rel="preload" href="https://cdn.jsdelivr.net/npm/katex@latest/dist/katex.min.css" as="style"
-    integrity="sha384-AfEj0r4/OFrOo5t7NnNe46zW/tFgW6x/bCJG8FqQCEo3+Aro6EYUG4+cU+KJWu/X" crossorigin="anonymous">
-  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@latest/dist/katex.min.css"
-    integrity="sha384-AfEj0r4/OFrOo5t7NnNe46zW/tFgW6x/bCJG8FqQCEo3+Aro6EYUG4+cU+KJWu/X" crossorigin="anonymous">
-  <script async src="https://cdn.jsdelivr.net/npm/katex@latest/dist/katex.min.js"
-    integrity="sha384-g7c+Jr9ZivxKLnZTDUhnkOnsh30B4H0rpLUpJ4jAIKs4fnJI+sEnkvrMWph2EDg4" crossorigin="anonymous"></script>
-
   {% include "fonts.html" %}
 </head>
 

diff --git a/docs/source/concepts.rst b/docs/source/concepts.rst
@@ -1,8 +1,8 @@
 Concepts
 ========
 
-Engine
-------
+Engine:
+-------
 
 The **essence** of the framework is the class :class:`~ignite.engine.engine.Engine`, an abstraction that loops a given number of times over
 provided data, executes a processing function and returns a result:
@@ -108,8 +108,8 @@ Argument ``batch`` in ``train_step`` function is user-defined and can contain an
 For multi-models training examples like GAN's, please, see our :doc:`examples`.
 
 
-Events and Handlers
--------------------
+Events and Handlers:
+--------------------
 
 To improve the :class:`~ignite.engine.engine.Engine`'s flexibility, an event system is introduced which facilitates interaction on each step of
 the run:
@@ -260,7 +260,7 @@ These events could be used to attach any handler and are fired using :meth:`~ign
 
 .. Note ::
 
-   See the source code of :class:`~ignite.contrib.engines.create_supervised_tbptt_trainer` for an example of usage of
+   See the source code of :func:`~ignite.contrib.engines.tbptt.create_supervised_tbptt_trainer` for an example of usage of
    custom events.
 
 If you want to use filtering with custom events (e.g. ``CustomEvents.CUSTOM_STARTED(every=5)``), you need to do 3 more things:
@@ -326,8 +326,8 @@ epoch:
 .. image:: _static/img/concepts/timeline_and_events.png
    :target: _static/img/concepts/timeline_and_events.png
 
-State
------
+State:
+------
 A state is introduced in :class:`~ignite.engine.engine.Engine` to store the output of the `process_function`, current epoch,
 iteration and other helpful information. Each :class:`~ignite.engine.engine.Engine` contains a :class:`~ignite.engine.events.State`,
 which includes the following:
@@ -364,7 +364,7 @@ every iteration.
     trainer.add_event_handler(Events.ITERATION_COMPLETED, on_iteration_completed)
 
 Since there is no restrictions on the output of `process_function`, Ignite provides `output_transform` argument for its
-:class:`~ignite.metrics` and :class:`~ignite.handlers`. Argument `output_transform` is a function used to transform `engine.state.output` for intended use. Below we'll see different types of `engine.state.output` and how to transform them.
+:ref:`ignite.metrics` and :ref:`ignite.handlers`. Argument `output_transform` is a function used to transform `engine.state.output` for intended use. Below we'll see different types of `engine.state.output` and how to transform them.
 
 In the code below, `engine.state.output` will be a list of loss, y_pred, y for the processed batch. If we want to attach :class:`~ignite.metrics.Accuracy` to the engine, `output_transform` will be needed to get y_pred and y from
 `engine.state.output`. Let's see how that is done:
@@ -431,8 +431,8 @@ batch, this is how the user can use `output_transform` to get y_pred and y from
           engine.state.new_attribute = 12345
 
 
-Metrics
--------
+Metrics:
+--------
 
 Library provides a list of out-of-the-box metrics for various Machine Learning tasks. Two way of computing
 metrics are supported : 1) online and 2) storing the entire output history.

diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -319,3 +319,23 @@ def run(self):
 
 # Patch original Autosummary
 sphinx.ext.autosummary.Autosummary = BetterAutosummary
+
+# --- autosummary config -----------------------------------------------------
+autosummary_generate = True
+
+# --- nitpicky config : check internal links are correct or not --------------
+nitpicky = True
+# ignore links which can't be referenced
+nitpick_ignore = [
+    ("py:class", ".."),
+    ("py:class", "TextIO"),
+    ("py:class", "torch.device"),
+    ("py:class", "_MpDeviceLoader"),
+    ("py:class", "torch.nn.modules.module.Module"),
+    ("py:class", "torch.optim.optimizer.Optimizer"),
+    ("py:class", "torch.utils.data.dataset.Dataset"),
+    ("py:class", "torch.utils.data.sampler.BatchSampler"),
+    ("py:class", "torch.cuda.amp.grad_scaler.GradScaler"),
+    ("py:class", "torch.optim.lr_scheduler._LRScheduler"),
+    ("py:class", "torch.utils.data.dataloader.DataLoader"),
+]