table indent (#255)

docs/requirements.txt

@@ -1,3 +1,4 @@
 sphinx
+sphinx-gallery
 sphinxcontrib-googleanalytics
 -e git://github.com/zhanghang1989/autorch_sphinx_theme.git#egg=autorch_sphinx_theme

docs/source/_static/theme_overrides.css

@@ -0,0 +1,13 @@
+/* override table width restrictions */
+@media screen and (min-width: 767px) {
+
+   .wy-table-responsive table td {
+      /* !important prevents the common CSS stylesheets from overriding
+         this as on RTD they are loaded after this stylesheet */
+      white-space: normal !important;
+   }
+
+   .wy-table-responsive {
+      overflow: visible !important;
+   }
+}

docs/source/conf.py

@@ -20,8 +20,14 @@
 # import os
 # import sys
 # sys.path.insert(0, os.path.abspath('.'))
+import os
+import sys
+sys.path.insert(0, os.path.abspath('.'))
 import encoding
 import autorch_sphinx_theme
+import glob
+import shutil
+from custom_directives import IncludeDirective, GalleryItemDirective, CustomGalleryItemDirective
 
 
 # -- General configuration ------------------------------------------------
@@ -33,6 +39,7 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
+
 extensions = [
     'sphinx.ext.autodoc',
     'sphinx.ext.autosummary',
@@ -43,6 +50,7 @@
     'sphinx.ext.mathjax',
     'sphinx.ext.napoleon',
     'sphinx.ext.viewcode',
+    #'sphinx_gallery.gen_gallery',
     # 'sphinxcontrib.googleanalytics',
 ]
 
@@ -88,7 +96,8 @@
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This patterns also effect to html_static_path and html_extra_path
-exclude_patterns = []
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+exclude_patterns += ['*/index.rst']
 
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'sphinx'
@@ -124,12 +133,9 @@
 
 html_context = {
     'css_files': [
-        'https://fonts.googleapis.com/css?family=Lato',
-        '_static/css/encoding.css'
-    ],
-}
-#'_static/css/hangzh.css'
-
+        '_static/theme_overrides.css',  # override wide tables in RTD theme
+        ],
+     }
 
 # -- Options for HTMLHelp output ------------------------------------------
 
@@ -155,6 +161,11 @@
     # Latex figure (float) alignment
     #
     # 'figure_align': 'htbp',
+    'preamble': r'''
+\newcolumntype{\Yl}[1]{>{\raggedright\arraybackslash}\Y{#1}}
+\newcolumntype{\Yr}[1]{>{\raggedleft\arraybackslash}\Y{#1}}
+\newcolumntype{\Yc}[1]{>{\centering\arraybackslash}\Y{#1}}
+''',
 }
 
 # Grouping the document tree into LaTeX files. List of tuples
@@ -186,3 +197,9 @@
      author, 'Encoding', 'One line description of project.',
      'Miscellaneous'),
 ]
+
+#def setup(app):
+#    # Custom directives
+#    app.add_directive('includenodoc', IncludeDirective)
+#    app.add_directive('galleryitem', GalleryItemDirective)
+#    app.add_directive('customgalleryitem', CustomGalleryItemDirective)

docs/source/custom_directives.py

@@ -0,0 +1,208 @@
+from docutils.parsers.rst import Directive, directives
+from docutils.statemachine import StringList 
+from docutils import nodes
+import re
+import os
+import sphinx_gallery
+
+try:
+    FileNotFoundError
+except NameError:
+    FileNotFoundError = IOError
+
+
+class IncludeDirective(Directive):
+    """Include source file without docstring at the top of file.
+
+    Implementation just replaces the first docstring found in file
+    with '' once.
+
+    Example usage:
+
+    .. includenodoc:: /beginner/examples_tensor/two_layer_net_tensor.py
+
+    """
+
+    # defines the parameter the directive expects
+    # directives.unchanged means you get the raw value from RST
+    required_arguments = 1
+    optional_arguments = 0
+    final_argument_whitespace = True
+    has_content = False
+    add_index = False
+
+    docstring_pattern = r'"""(?P<docstring>(?:.|[\r\n])*?)"""\n'
+    docstring_regex = re.compile(docstring_pattern)
+
+    def run(self):
+        document = self.state.document
+        env = document.settings.env
+        rel_filename, filename = env.relfn2path(self.arguments[0])
+
+        try:
+            text = open(filename).read()
+            text_no_docstring = self.docstring_regex.sub('', text, count=1)
+
+            code_block = nodes.literal_block(text=text_no_docstring)
+            return [code_block]
+        except FileNotFoundError as e:
+            print(e)
+            return []
+
+
+class GalleryItemDirective(Directive):
+    """
+    Create a sphinx gallery thumbnail for insertion anywhere in docs.
+
+    Optionally, you can specify the custom figure and intro/tooltip for the
+    thumbnail.
+
+    Example usage:
+
+    .. galleryitem:: intermediate/char_rnn_generation_tutorial.py
+        :figure: _static/img/char_rnn_generation.png
+        :intro: Put your custom intro here.
+
+    If figure is specified, a thumbnail will be made out of it and stored in
+    _static/thumbs. Therefore, consider _static/thumbs as a 'built' directory.
+    """
+
+    required_arguments = 1
+    optional_arguments = 0
+    final_argument_whitespace = True
+    option_spec = {'figure': directives.unchanged,
+                   'intro': directives.unchanged}
+    has_content = False
+    add_index = False
+
+    def run(self):
+        args = self.arguments
+        fname = args[-1]
+
+        env = self.state.document.settings.env
+        fname, abs_fname = env.relfn2path(fname)
+        basename = os.path.basename(fname)
+        dirname = os.path.dirname(fname)
+
+        try:
+            if 'intro' in self.options:
+                intro = self.options['intro'][:195] + '...'
+            else:
+                _, blocks = sphinx_gallery.gen_rst.split_code_and_text_blocks(abs_fname)
+                intro, _ = sphinx_gallery.gen_rst.extract_intro_and_title(abs_fname, blocks[0][1])
+
+            thumbnail_rst = sphinx_gallery.backreferences._thumbnail_div(
+                dirname, basename, intro)
+
+            if 'figure' in self.options:
+                rel_figname, figname = env.relfn2path(self.options['figure'])
+                save_figname = os.path.join('_static/thumbs/',
+                                            os.path.basename(figname))
+
+                try:
+                    os.makedirs('_static/thumbs')
+                except OSError:
+                    pass
+
+                sphinx_gallery.gen_rst.scale_image(figname, save_figname,
+                                                   400, 280)
+                # replace figure in rst with simple regex
+                thumbnail_rst = re.sub(r'..\sfigure::\s.*\.png',
+                                       '.. figure:: /{}'.format(save_figname),
+                                       thumbnail_rst)
+
+            thumbnail = StringList(thumbnail_rst.split('\n'))
+            thumb = nodes.paragraph()
+            self.state.nested_parse(thumbnail, self.content_offset, thumb)
+
+            return [thumb]
+        except FileNotFoundError as e:
+            print(e)
+            return []
+
+
+GALLERY_TEMPLATE = """
+.. raw:: html
+
+    <div class="sphx-glr-thumbcontainer" tooltip="{tooltip}">
+
+.. only:: html
+
+    .. figure:: {thumbnail}
+
+        {description}
+
+.. raw:: html
+
+    </div>
+"""
+
+
+class CustomGalleryItemDirective(Directive):
+    """Create a sphinx gallery style thumbnail.
+
+    tooltip and figure are self explanatory. Description could be a link to
+    a document like in below example. 
+
+    Example usage:
+
+    .. customgalleryitem::
+        :tooltip: I am writing this tutorial to focus specifically on NLP for people who have never written code in any deep learning framework
+        :figure: /_static/img/thumbnails/babel.jpg
+        :description: :doc:`/beginner/deep_learning_nlp_tutorial`
+
+    If figure is specified, a thumbnail will be made out of it and stored in
+    _static/thumbs. Therefore, consider _static/thumbs as a 'built' directory.
+    """
+
+    required_arguments = 0
+    optional_arguments = 0
+    final_argument_whitespace = True
+    option_spec = {'tooltip': directives.unchanged,
+                   'figure': directives.unchanged,
+                   'description': directives.unchanged}
+
+    has_content = False
+    add_index = False
+
+    def run(self):
+        try:
+            if 'tooltip' in self.options:
+                tooltip = self.options['tooltip'][:195] + '...'
+            else:
+                raise ValueError('tooltip not found')
+
+            if 'figure' in self.options:
+                env = self.state.document.settings.env
+                rel_figname, figname = env.relfn2path(self.options['figure'])
+                thumbnail = os.path.join('_static/thumbs/', os.path.basename(figname))
+
+                try:
+                    os.makedirs('_static/thumbs')
+                except FileExistsError:
+                    pass
+
+                sphinx_gallery.gen_rst.scale_image(figname, thumbnail, 400, 280)
+            else:
+                thumbnail = '_static/img/thumbnails/default.png'
+
+            if 'description' in self.options:
+                description = self.options['description']
+            else:
+                raise ValueError('description not doc found')
+
+        except FileNotFoundError as e:
+            print(e)
+            return []
+        except ValueError as e:
+            print(e)
+            raise
+            return []
+
+        thumbnail_rst = GALLERY_TEMPLATE.format(tooltip=tooltip,
+                                                thumbnail=thumbnail,
+                                                description=description)
+        thumbnail = StringList(thumbnail_rst.split('\n'))
+        thumb = nodes.paragraph()
+        self.state.nested_parse(thumbnail, self.content_offset, thumb)
+        return [thumb]

docs/source/experiments/segmentation.rst

@@ -10,8 +10,8 @@ Install Package
 
 - Install PyTorch Encoding (if not yet). Please follow the installation guide `Installing PyTorch Encoding <../notes/compile.html>`_.
 
-Test Pre-trained Model
-----------------------
+Get Pre-trained Model
+---------------------
 
 .. hint::
     The model names contain the training information. For instance ``FCN_ResNet50_PContext``:
@@ -23,34 +23,23 @@ Test Pre-trained Model
 
         model = encoding.models.get_model('FCN_ResNet50_PContext', pretrained=True)
 
-    Prepare the datasets by runing the scripts in the ``scripts/`` folder, for example preparing ``PASCAL Context`` dataset::
-
-        python scripts/prepare_pcontext.py
-    
-    The test script is in the ``experiments/segmentation/`` folder. For evaluating the model (using MS),
-    for example ``Encnet_ResNet50_PContext``::
-
-        python test.py --dataset PContext --model-zoo Encnet_ResNet50_PContext --eval
-        # pixAcc: 0.792, mIoU: 0.510: 100%|████████████████████████| 1276/1276 [46:31<00:00,  2.19s/it]
-
-    The command for training the model can be found by clicking ``cmd`` in the table.
+    After clicking ``cmd`` in the table, the command for training the model can be found below the table.
 
 .. role:: raw-html(raw)
    :format: html
 
-+----------------------------------+-----------+-----------+----------------------------------------------------------------------------------------------+
-| Model                            | pixAcc    | mIoU      | Command                                                                                      |
-+==================================+===========+===========+==============================================================================================+
-| Encnet_ResNet50_PContext         | 79.2%     | 51.0%     | :raw-html:`<a href="javascript:toggleblock('cmd_enc50_pcont')" class="toggleblock">cmd</a>`  |
-+----------------------------------+-----------+-----------+----------------------------------------------------------------------------------------------+
-| EncNet_ResNet101_PContext        | 80.7%     | 54.1%     | :raw-html:`<a href="javascript:toggleblock('cmd_enc101_pcont')" class="toggleblock">cmd</a>` |
-+----------------------------------+-----------+-----------+----------------------------------------------------------------------------------------------+
-| EncNet_ResNet50_ADE              | 80.1%     | 41.5%     | :raw-html:`<a href="javascript:toggleblock('cmd_enc50_ade')" class="toggleblock">cmd</a>`    |
-+----------------------------------+-----------+-----------+----------------------------------------------------------------------------------------------+
-| EncNet_ResNet101_ADE             | 81.3%     | 44.4%     | :raw-html:`<a href="javascript:toggleblock('cmd_enc101_ade')" class="toggleblock">cmd</a>`   |
-+----------------------------------+-----------+-----------+----------------------------------------------------------------------------------------------+
-| EncNet_ResNet101_VOC             | N/A       | 85.9%     | :raw-html:`<a href="javascript:toggleblock('cmd_enc101_voc')" class="toggleblock">cmd</a>`   |
-+----------------------------------+-----------+-----------+----------------------------------------------------------------------------------------------+
+
+.. tabularcolumns:: |>{\centering\arraybackslash}\X{4}{5}|>{\raggedleft\arraybackslash}\X{1}{5}|
+
+==============================================================================  ==============    ==============    =============================================================================================
+Model                                                                           pixAcc            mIoU              Command                                                                                      
+==============================================================================  ==============    ==============    =============================================================================================
+Encnet_ResNet50_PContext                                                        79.2%             51.0%             :raw-html:`<a href="javascript:toggleblock('cmd_enc50_pcont')" class="toggleblock">cmd</a>`  
+EncNet_ResNet101_PContext                                                       80.7%             54.1%             :raw-html:`<a href="javascript:toggleblock('cmd_enc101_pcont')" class="toggleblock">cmd</a>` 
+EncNet_ResNet50_ADE                                                             80.1%             41.5%             :raw-html:`<a href="javascript:toggleblock('cmd_enc50_ade')" class="toggleblock">cmd</a>`    
+EncNet_ResNet101_ADE                                                            81.3%             44.4%             :raw-html:`<a href="javascript:toggleblock('cmd_enc101_ade')" class="toggleblock">cmd</a>`   
+EncNet_ResNet101_VOC                                                            N/A               85.9%             :raw-html:`<a href="javascript:toggleblock('cmd_enc101_voc')" class="toggleblock">cmd</a>`   
+==============================================================================  ==============    ==============    =============================================================================================
 
 
 .. raw:: html
@@ -88,6 +77,19 @@ Test Pre-trained Model
     CUDA_VISIBLE_DEVICES=0,1,2,3 python train.py --dataset Pascal_voc --model encnet --aux  --se-loss --backbone resnet101 --lr 0.0001 --syncbn --ngpus 4 --checkname res101 --resume runs/Pascal_aug/encnet/res101/checkpoint.params --ft
     </code>
 
+Test Pretrained
+~~~~~~~~~~~~~~~
+
+- Prepare the datasets by runing the scripts in the ``scripts/`` folder, for example preparing ``PASCAL Context`` dataset::
+
+      python scripts/prepare_pcontext.py
+  
+- The test script is in the ``experiments/segmentation/`` folder. For evaluating the model (using MS),
+  for example ``Encnet_ResNet50_PContext``::
+
+      python test.py --dataset PContext --model-zoo Encnet_ResNet50_PContext --eval
+      # pixAcc: 0.792, mIoU: 0.510: 100%|████████████████████████| 1276/1276 [46:31<00:00,  2.19s/it]
+
 Quick Demo
 ~~~~~~~~~~