Merge pull request #73 from docascode/yitian/ut

[dev] Add more unit tests and fix old unit tests.

.pylint

@@ -0,0 +1,12 @@
+# Based on:
+# https://github.com/kpreid/shinysdr/blob/master/pylintrc
+
+[MASTER]
+# XXX should be changed to your project folder
+# see http://stackoverflow.com/a/37238692/3828891 for explanation
+init-hook='base_dir="."; import sys,os,re; _re=re.search(r".+\/" + base_dir, os.getcwd()); project_dir = _re.group() if _re else os.path.join(os.getcwd(), base_dir); sys.path.append(project_dir)'
+
+[MESSAGES CONTROL]
+# Find available symbolic names in:
+# https://docs.pylint.org/features.html
+disable=locally-disabled,trailing-whitespace,fixme,missing-docstring,protected-access,invalid-name,super-init-not-called,star-args,no-self-argument,inherit-non-class,no-method-argument,no-self-use,unused-argument,too-many-return-statements,too-many-branches,too-many-function-args,too-many-instance-attributes,too-many-locals,bad-continuation,unnecessary-lambda,redefined-variable-type,global-statement,line-too-long,mixed-indentation,bad-whitespace,missing-final-newline

.travis.yml

@@ -3,10 +3,8 @@ python:
  - 3.5
 sudo: false
 env:
- - TOX_ENV=py27
  - TOX_ENV=py35
  - TOX_ENV=docs
- - TOX_ENV=lint
 install:
  - pip install tox
 script:

README.rst

@@ -1,13 +1,10 @@
 Sphinx DocFX YAML
 =================
 
-.. image:: https://travis-ci.org/ericholscher/sphinx-docfx-yaml.svg?branch=master
-   :target: https://travis-ci.org/ericholscher/sphinx-docfx-yaml
+.. image:: https://travis-ci.org/docascode/sphinx-docfx-yaml.svg?branch=master
+   :target: https://travis-ci.org/docascode/sphinx-docfx-yaml
 
-.. image:: https://ci.appveyor.com/api/projects/status/m9t5a331de14mwfi/branch/master?svg=true
-   :target: https://ci.appveyor.com/project/ericholscher/sphinx-docfx-yaml
-
-Sphinx DocFX YAML is an exporter for the Sphinx Autodoc module into `DocFX YAML <https://dotnet.github.io/docfx/spec/metadata_format_spec.html>`_. 
+Sphinx DocFX YAML is an exporter for the Sphinx Autodoc module into `DocFX YAML <https://dotnet.github.io/docfx/spec/metadata_format_spec.html>`_.
 
 You can read the full documentation online at http://sphinx-docfx-yaml.readthedocs.io
 
@@ -60,7 +57,7 @@ the ``docfx_yaml`` will contain the YAML files that are output.
 
 ..  Modes
     -----
-    
+
     There are two output modes that specify the structure of the YAML files.
     The first is ``module`` which means that the YAML files will be output in files corresponding to the name of their module.
     The second modes is ``rst`` which outputs them in the same structure as the RST files they were defined in.

docfx_yaml/directives.py

@@ -9,6 +9,7 @@
 
 from .nodes import remarks
 
+
 class RemarksDirective(Directive):
     """
     Class to enable remarks directive.
@@ -20,7 +21,7 @@ class RemarksDirective(Directive):
     # Directive class must override run function.
     def run(self):
         self.assert_has_content()
-        
+
         text = '\n'.join(self.content)
 
         return_nodes = []

docfx_yaml/extension.py

@@ -29,7 +29,7 @@
 from .nodes import remarks
 
 
-class bcolors:
+class Bcolors:
     HEADER = '\033[95m'
     OKBLUE = '\033[94m'
     OKGREEN = '\033[92m'
@@ -39,10 +39,12 @@ class bcolors:
     BOLD = '\033[1m'
     UNDERLINE = '\033[4m'
 
+
 try:
     from conf import *
 except ImportError:
-    print(bcolors.FAIL + 'can not import conf.py! you should have a conf.py in working project folder' + bcolors.ENDC)
+    print(Bcolors.FAIL + 'can not import conf.py! '
+    'you should have a conf.py in working project folder' + Bcolors.ENDC)
 
 METHOD = 'method'
 FUNCTION = 'function'
@@ -147,9 +149,11 @@ def _refact_example_in_module_summary(lines):
             block_lines[:] = []
         elif example_block_flag:
             if line == '   ':  # origianl line is blank line ('\n').
-                line = '\n' # after outer ['\n'.join] operation, this '\n' will be appended to previous line then. BINGO!
+                line = '\n'  # after outer ['\n'.join] operation,
+                             # this '\n' will be appended to previous line then. BINGO!
             elif line.startswith('   '):
-                # will be indented by 4 spaces according to yml block syntax. https://learnxinyminutes.com/docs/yaml/
+                # will be indented by 4 spaces according to yml block syntax.
+                # https://learnxinyminutes.com/docs/yaml/
                 line = ' ' + line + '\n'
             block_lines.append(line)
 
@@ -384,7 +388,7 @@ def insert_children_on_module(app, _type, datam):
                 obj['type'] == MODULE and \
                 obj[MODULE] == datam[MODULE]:
             obj['children'].append(datam['uid'])
-            
+
             # If it is a function, add this to its module. No need for class and module since this is
             # done before calling this function.
             insert_module.append(datam)
@@ -528,7 +532,7 @@ def convert_module_to_package_if_needed(obj):
                     # Raise up summary
                     if 'summary' in obj['syntax'] and obj['syntax']['summary']:
                         obj['summary'] = obj['syntax'].pop('summary')
-                    
+
                     # Raise up remarks
                     if 'remarks' in obj['syntax'] and obj['syntax']['remarks']:
                         obj['remarks'] = obj['syntax'].pop('remarks')
@@ -552,10 +556,10 @@ def convert_module_to_package_if_needed(obj):
                     # add content of temp list 'added_attribute' to children and yaml_data
                     if 'added_attribute' in obj['syntax'] and obj['syntax']['added_attribute']:
                         added_attribute = obj['syntax'].pop('added_attribute')
-                        for attrData in added_attribute: 
+                        for attrData in added_attribute:
                             existed_Data = next((n for n in yaml_data if n['uid'] == attrData['uid']), None)
                             if existed_Data:
-                                # Update data for already existed one which has attribute comment in source file 
+                                # Update data for already existed one which has attribute comment in source file
                                 existed_Data.update(attrData)
                             else:
                                 obj.get('children', []).append(attrData['uid'])

tests/example/doc/conf.py

@@ -0,0 +1,28 @@
+# -*- coding: utf-8 -*-
+
+import sys
+import os
+
+sys.path.insert(0, os.path.dirname(os.path.dirname(__file__)))
+
+source_suffix = '.rst'
+master_doc = 'index'
+project = u'example'
+copyright = u'2018, Microsoft'
+author = u'Yiding Tian'
+version = '0.1'
+release = '0.1'
+language = None
+exclude_patterns = ['_build']
+pygments_style = 'sphinx'
+todo_include_todos = False
+html_theme = 'alabaster'
+html_static_path = ['_static']
+htmlhelp_basename = 'Example Document'
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.napoleon',
+    'sphinx.ext.intersphinx',
+    'docfx_yaml.extension'
+]
+intersphinx_mapping = {'python': ('https://docs.python.org/3.6', None)}

tests/example/doc/format.google.rst

@@ -0,0 +1,22 @@
+format\.google package
+======================
+
+Submodules
+----------
+
+format\.google\.foo module
+--------------------------
+
+.. automodule:: format.google.foo
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+
+Module contents
+---------------
+
+.. automodule:: format.google
+    :members:
+    :undoc-members:
+    :show-inheritance:

tests/example/doc/format.numpy.rst

@@ -0,0 +1,22 @@
+format\.numpy package
+=====================
+
+Submodules
+----------
+
+format\.numpy\.foo module
+-------------------------
+
+.. automodule:: format.numpy.foo
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+
+Module contents
+---------------
+
+.. automodule:: format.numpy
+    :members:
+    :undoc-members:
+    :show-inheritance:

tests/example/doc/format.rst

@@ -0,0 +1,19 @@
+format package
+==============
+
+Subpackages
+-----------
+
+.. toctree::
+
+    format.google
+    format.numpy
+    format.rst
+
+Module contents
+---------------
+
+.. automodule:: format
+    :members:
+    :undoc-members:
+    :show-inheritance:

tests/example/doc/format.rst.rst

@@ -0,0 +1,38 @@
+format\.rst package
+===================
+
+Submodules
+----------
+
+format\.rst\.directives module
+------------------------------
+
+.. automodule:: format.rst.directives
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+format\.rst\.enum module
+------------------------
+
+.. automodule:: format.rst.enum
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+format\.rst\.foo module
+-----------------------
+
+.. automodule:: format.rst.foo
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+
+Module contents
+---------------
+
+.. automodule:: format.rst
+    :members:
+    :undoc-members:
+    :show-inheritance:

tests/example/doc/nspkg.native.native_foo.rst

@@ -0,0 +1,10 @@
+nspkg\.native\.native\_foo package
+==================================
+
+Module contents
+---------------
+
+.. automodule:: nspkg.native.native_foo
+    :members:
+    :undoc-members:
+    :show-inheritance:

tests/example/doc/nspkg.pkg_resources.pkg_resources_foo.rst

@@ -0,0 +1,10 @@
+nspkg\.pkg\_resources\.pkg\_resources\_foo package
+==================================================
+
+Module contents
+---------------
+
+.. automodule:: nspkg.pkg_resources.pkg_resources_foo
+    :members:
+    :undoc-members:
+    :show-inheritance:

tests/example/doc/nspkg.pkg_resources.rst

@@ -0,0 +1,17 @@
+nspkg\.pkg\_resources package
+=============================
+
+Subpackages
+-----------
+
+.. toctree::
+
+    nspkg.pkg_resources.pkg_resources_foo
+
+Module contents
+---------------
+
+.. automodule:: nspkg.pkg_resources
+    :members:
+    :undoc-members:
+    :show-inheritance:

tests/example/doc/nspkg.pkgutil.pkgutil_foo.rst

@@ -0,0 +1,10 @@
+nspkg\.pkgutil\.pkgutil\_foo package
+====================================
+
+Module contents
+---------------
+
+.. automodule:: nspkg.pkgutil.pkgutil_foo
+    :members:
+    :undoc-members:
+    :show-inheritance:

tests/example/doc/nspkg.pkgutil.rst

@@ -0,0 +1,17 @@
+nspkg\.pkgutil package
+======================
+
+Subpackages
+-----------
+
+.. toctree::
+
+    nspkg.pkgutil.pkgutil_foo
+
+Module contents
+---------------
+
+.. automodule:: nspkg.pkgutil
+    :members:
+    :undoc-members:
+    :show-inheritance:

tests/example/doc/nspkg.rst

@@ -0,0 +1,18 @@
+nspkg package
+=============
+
+Subpackages
+-----------
+
+.. toctree::
+
+    nspkg.pkg_resources
+    nspkg.pkgutil
+
+Module contents
+---------------
+
+.. automodule:: nspkg
+    :members:
+    :undoc-members:
+    :show-inheritance:

tests/example/format/__init__.py

@@ -0,0 +1,4 @@
+# coding: utf-8
+
+""" Package used to test rst-style, google-style and numpy-style docstrings.
+"""

tests/example/format/google/__init__.py

@@ -0,0 +1,2 @@
+# coding: utf-8
+# This package is used to test google style docstring.