Click docs

[Ublimjo]

sphinx.util.compat is removed in 1.7.0b1

sphinx-build -b html -d _build/doctrees   . _build/html.  
Running Sphinx v1.7.2.  
   
Extension error:.  
Could not import extension clickdoctools (exception: cannot import name 'Directive').  
make: *** [Makefile:40: html] Error 2.  

[PyDever]

Also consider posting your setup and make code next time.

[dawranliou]

@Ublimjo you are using the Makefile under docs/, right? I was able to reproduce the issue by:

$ cd docs/
$ make html
sphinx-build -b html -d _build/doctrees   . _build/html
Running Sphinx v1.7.4

Extension error:
Could not import extension clickdoctools (exception: cannot import name 'Directive')
make: *** [html] Error 2

With the verbose flag turned on:

$ sphinx-build -b html -d _build/doctrees   . _build/html -v
Running Sphinx v1.7.4
Original exception:
Traceback (most recent call last):
  File "/Users/dawran6/.local/share/virtualenvs/click--APYMEB6/lib/python3.6/site-packages/sphinx/registry.py", line 315, in load_extension
    mod = __import__(extname, None, None, ['setup'])
  File "/Users/dawran6/Developer/click/docs/clickdoctools.py", line 18, in <module>
    from sphinx.util.compat import Directive
ImportError: cannot import name 'Directive'


Traceback (most recent call last):
  File "/Users/dawran6/.local/share/virtualenvs/click--APYMEB6/lib/python3.6/site-packages/sphinx/registry.py", line 315, in load_extension
    mod = __import__(extname, None, None, ['setup'])
  File "/Users/dawran6/Developer/click/docs/clickdoctools.py", line 18, in <module>
    from sphinx.util.compat import Directive
ImportError: cannot import name 'Directive'

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "/Users/dawran6/.local/share/virtualenvs/click--APYMEB6/lib/python3.6/site-packages/sphinx/cmdline.py", line 303, in main
    args.warningiserror, args.tags, args.verbosity, args.jobs)
  File "/Users/dawran6/.local/share/virtualenvs/click--APYMEB6/lib/python3.6/site-packages/sphinx/application.py", line 191, in __init__
    self.setup_extension(extension)
  File "/Users/dawran6/.local/share/virtualenvs/click--APYMEB6/lib/python3.6/site-packages/sphinx/application.py", line 411, in setup_extension
    self.registry.load_extension(self, extname)
  File "/Users/dawran6/.local/share/virtualenvs/click--APYMEB6/lib/python3.6/site-packages/sphinx/registry.py", line 318, in load_extension
    raise ExtensionError(__('Could not import extension %s') % extname, err)
sphinx.errors.ExtensionError: Could not import extension clickdoctools (exception: cannot import name 'Directive')

Extension error:
Could not import extension clickdoctools (exception: cannot import name 'Directive')

[dawranliou]

From http://www.sphinx-doc.org/en/master/changes.html#id37:

Deprecated
1.6b1
sphinx.util.compat.Directive class is now deprecated. Please use instead docutils.parsers.rst.Directive

We could:

1. Just change the import statement and support 1.7+, or
2. Back-port by using this try-except block:

try:
    from sphinx.util.compat import Directive
except ImportError:
    from docutils.parsers.rst import Directive

IMO 1. is cleaner and easier to maintain but it also breaks backward compatibility.

[dawranliou]

@davidism agreed with 1.

More issues surfaced while using Python3, like the usage of dict.iteritems or isinstance(input, unicode). I'm fixing those as well. See #719.

[dawranliou]

Found a related PR #883