Cards of code snippets on index page (#4627)

docs/extension/codesnippetcard.py

+"""
+Code snippet card, used in index page.
+"""
+
+from docutils.parsers.rst import Directive, directives
+from docutils.statemachine import StringList
+from docutils import nodes
+
+from sphinx.addnodes import pending_xref
+
+
+CARD_TEMPLATE_HEADER = """
+.. raw:: html
+
+    <div class="codesnippet-card admonition">
+
+    <div class="codesnippet-card-body">
+
+    <div class="codesnippet-card-title-container">
+
+    <div class="codesnippet-card-icon">
+
+.. image:: {icon}
+
+.. raw:: html
+
+    </div>
+
+    <h3>{title}</h3>
+    </div>
+
+"""
+
+CARD_TEMPLATE_FOOTER = """
+.. raw:: html
+
+    </div>
+"""
+
+CARD_TEMPLATE_LINK_CONTAINER_HEADER = """
+.. raw:: html
+
+    <div class="codesnippet-card-footer">
+"""
+
+CARD_TEMPLATE_LINK = """
+.. raw:: html
+
+    <div class="codesnippet-card-link">
+    For a full tutorial, please go here.
+    <span class="material-icons right">arrow_forward</span>
+    </div>
+"""
+
+
+class CodeSnippetCardDirective(Directive):
+    option_spec = {
+        'icon': directives.unchanged,
+        'title': directives.unchanged,
+        'link': directives.unchanged,
+    }
+
+    has_content = True
+
+    def run(self):
+        anchor_node = nodes.paragraph()
+
+        try:
+            title = self.options['title']
+            link = directives.uri(self.options['link'])
+            icon = directives.uri(self.options['icon'])
+        except ValueError as e:
+            print(e)
+            raise
+
+        # header, title, icon...
+        card_rst = CARD_TEMPLATE_HEADER.format(title=title, icon=icon)
+        card_list = StringList(card_rst.split('\n'))
+        self.state.nested_parse(card_list, self.content_offset, anchor_node)
+
+        # code snippet
+        self.state.nested_parse(self.content, self.content_offset, anchor_node)
+
+        # close body
+        self.state.nested_parse(StringList(CARD_TEMPLATE_FOOTER.split('\n')), self.content_offset, anchor_node)
+
+        # start footer
+        self.state.nested_parse(StringList(CARD_TEMPLATE_LINK_CONTAINER_HEADER.split('\n')), self.content_offset, anchor_node)
+
+        # full tutorial link
+        link_node = pending_xref(CARD_TEMPLATE_LINK,
+                                 reftype='doc',
+                                 refdomain='std',
+                                 reftarget=link,
+                                 refexplicit=False,
+                                 refwarn=True,
+                                 refkeepformat=True)
+        # refkeepformat is handled in `patch_autodoc.py`
+        self.state.nested_parse(StringList(CARD_TEMPLATE_LINK.split('\n')), self.content_offset, link_node)
+        anchor_node += link_node
+
+        # close footer
+        self.state.nested_parse(StringList(CARD_TEMPLATE_FOOTER.split('\n')), self.content_offset, anchor_node)
+
+        # close whole
+        self.state.nested_parse(StringList(CARD_TEMPLATE_FOOTER.split('\n')), self.content_offset, anchor_node)
+
+        return [anchor_node]
+
+
+def setup(app):
+    app.add_directive('codesnippetcard', CodeSnippetCardDirective)

docs/source/conf.py

@@ -60,6 +60,7 @@ extensions = [
     'tutorial_links',  # this has to be after sphinx-gallery
     'inplace_translation',
     'cardlinkitem',
+    'codesnippetcard',
     'patch_docutils',
     'patch_autodoc',
 ]

docs/source/index.rst

@@ -46,7 +46,145 @@ Neural Network Intelligence
     How to Contribute <contribution>
     Change Log <Release>
 
+.. raw:: html
+
+   <div class="codesnippet-card-container">
+
+.. codesnippetcard::
+   :icon: ../img/thumbnails/hpo-icon-small.png
+   :title: Hyper-parameter Tuning
+   :link: autotune_ref
+
+   .. code-block::
+
+      params = nni.get_next_parameter()
+
+      class Net(nn.Module):
+          ...
+
+      model = Net()
+      optimizer = optim.SGD(model.parameters(),
+                            params['lr'],
+                            params['momentum'])
+
+      for epoch in range(10):
+          train(...)
+
+      accuracy = test(model)
+      nni.report_final_result(accuracy)
+
+.. codesnippetcard::
+   :icon: ../img/thumbnails/pruning-icon-small.png
+   :title: Model Pruning
+   :link: tutorials/pruning_quick_start_mnist
+
+   .. code-block::
+
+      # define a config_list
+      config = [{
+          'sparsity': 0.8,
+          'op_types': ['Conv2d']
+      }]
+
+      # generate masks for simulated pruning
+      wrapped_model, masks = \
+          L1NormPruner(model, config). \
+          compress()
+
+      # apply the masks for real speed up
+      ModelSpeedup(unwrapped_model, input, masks). \
+          speedup_model()
+
+.. codesnippetcard::
+   :icon: ../img/thumbnails/quantization-icon-small.png
+   :title: Quantization
+   :link: tutorials/quantization_speed_up
+
+   .. code-block::
+
+      # define a config_list
+      config = [{
+          'quant_types': ['input', 'weight'],
+          'quant_bits': {'input': 8, 'weight': 8},
+          'op_types': ['Conv2d']
+      }]
+
+      # in case quantizer needs a extra training
+      quantizer = QAT_Quantizer(model, config)
+      quantizer.compress()
+      # Training...
+
+      # export calibration config and
+      # generate TensorRT engine for real speed up
+      calibration_config = quantizer.export_model(
+          model_path, calibration_path)
+      engine = ModelSpeedupTensorRT(
+          model, input_shape, config=calib_config)
+      engine.compress()
+
+.. codesnippetcard::
+   :icon: ../img/thumbnails/multi-trial-nas-icon-small.png
+   :title: Neural Architecture Search
+   :link: tutorials/hello_nas
+
+   .. code-block:: diff
+
+      # define model space
+      -   self.conv2 = nn.Conv2d(32, 64, 3, 1)
+      +   self.conv2 = nn.LayerChoice([
+      +       nn.Conv2d(32, 64, 3, 1),
+      +       DepthwiseSeparableConv(32, 64)
+      +   ])
+      # search strategy + evaluator
+      strategy = RegularizedEvolution()
+      evaluator = FunctionalEvaluator(
+          train_eval_fn)
+
+      # run experiment
+      RetiariiExperiment(model_space,
+          evaluator, strategy).run()
+
+.. codesnippetcard::
+   :icon: ../img/thumbnails/one-shot-nas-icon-small.png
+   :title: One-shot NAS
+   :link: nas/index
+
+   .. code-block::
+
+      # define model space
+      space = AnySearchSpace()
+
+      # get a darts trainer
+      trainer = DartsTrainer(space, loss, metrics)
+      trainer.fit()
+
+      # get final searched architecture
+      arch = trainer.export()
+
+.. codesnippetcard::
+   :icon: ../img/thumbnails/feature-engineering-icon-small.png
+   :title: Feature Engineering
+   :link: FeatureEngineering/Overview
+
+   .. code-block::
+
+      selector = GBDTSelector()
+      selector.fit(
+          X_train, y_train,
+          lgb_params=lgb_params,
+          eval_ratio=eval_ratio,
+          early_stopping_rounds=10,
+          importance_type='gain',
+          num_boost_round=1000)
+
+      # get selected features
+      features = selector.get_selected_features()
+
+.. End of code snippet card
+
+.. raw:: html
 
+   </div>
 
 .. raw:: html
 

docs/source/index_zh.rst

-.. 1a07f898d4bde4f9566abae45239cad9
+.. 1d789e3c2bde22f1392654fde31a688a
 
 ###########################
 Neural Network Intelligence

docs/static/css/material_custom.css

+/* Material icon: https://developers.google.com/fonts/docs/material_icons */
+/* Icon library: https://fonts.google.com/icons */
+.material-icons {
+    font-family: 'Material Icons';
+    font-weight: normal;
+    font-style: normal;
+    font-size: 24px;  /* Preferred icon size */
+    display: inline-block;
+    line-height: 1;
+    text-transform: none;
+    letter-spacing: normal;
+    word-wrap: normal;
+    white-space: nowrap;
+    direction: ltr;
+  
+    /* Support for all WebKit browsers. */
+    -webkit-font-smoothing: antialiased;
+    /* Support for Safari and Chrome. */
+    text-rendering: optimizeLegibility;
+  
+    /* Support for Firefox. */
+    -moz-osx-font-smoothing: grayscale;
+  
+    /* Support for IE. */
+    font-feature-settings: 'liga';
+}
+
 /* viewcode link should have left padding */
 span.viewcode-link {
     padding-left: 0.6rem;
@@ -53,6 +80,92 @@ nav.md-tabs .md-tabs__item:not(:last-child) .md-tabs__link:after {
     padding-right: 1em;
 }
 
+/* Similar to cardlink, but used in codesnippet in index page. see sphinx_gallery.css */
+.codesnippet-card-container {
+    display: flex;
+    flex-flow: wrap row;
+}
+
+.codesnippet-card.admonition {
+    border-left: 0;
+    padding: 0;
+    margin: .5rem 1rem 1rem 0rem;
+    width: 47%;
+}
+
+@media only screen and (max-width:59.9375em) {
+    .codesnippet-card.admonition {
+        width: 100%;
+    }
+}
+
+.codesnippet-card .codesnippet-card-body {
+    min-height: 4rem;
+    position: relative;
+    padding: 0.9rem 0.9rem 3rem 0.9rem;
+}
+
+.codesnippet-card .codesnippet-card-footer {
+    padding: 0.8rem 0.9rem;
+    border-top: 1px solid #ddd;
+    margin: 0 !important;
+    position: absolute;
+    bottom: 0;
+    width: 100%;
+}
+
+.codesnippet-card a:not(:hover) {
+    color: rgba(0, 0, 0, .68);
+}
+
+.codesnippet-card-title-container {
+    margin-top: 0.3rem;
+    position: relative;
+}
+
+.codesnippet-card-title-container h3 {
+    padding-left: 2.5rem;
+    line-height: 1.8rem;
+    height: 1.8rem;
+    margin-top: 0;
+}
+
+.codesnippet-card-icon {
+    position: absolute;
+    top: 0;
+    left: 0;
+}
+
+.codesnippet-card-icon img {
+    max-width: 100%;
+    max-height: 100%;
+    /* horizontal and vertical center */
+    /* https://stackoverflow.com/questions/7273338/how-to-vertically-align-an-image-inside-a-div */
+    text-align: center;
+    vertical-align: middle;
+    position: absolute;
+    left: 0;
+    right: 0;
+    top: 0;
+    bottom: 0;
+    margin: auto;
+}
+
+.codesnippet-card-icon {
+    width: 1.8rem;
+    height: 1.8rem;
+    padding: 0;
+}
+
+.codesnippet-card-link {
+    position: relative;
+}
+
+.codesnippet-card-link .material-icons {
+    position: absolute;
+    right: 0;
+}
+
 /* fixes reference overlapping issue */
 /* This is originally defined to be negative in application_fixes.css */
 /* They did that to ensure the header doesn't disappear in jump links */