doc: add proper documentation

[stephanlachnit]

Closes #73.

A couple of notes:

• AND, OR and NOT have to be excluded via exclude-members, else one will get

  WARNING: error while formatting arguments for license_expression.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND: Handler <function update_annotations_using_type_comments at 0x7fda1f35b3a0> for event 'autodoc-before-process-signature' threw an exception (exception: maximum recursion depth exceeded while calling a Python object)
  WARNING: error while formatting signature for license_expression.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND.AND: Handler <function record_typehints at 0x7fda1f35b550> for event 'autodoc-process-signature' threw an exception (exception: maximum recursion depth exceeded in comparison)
  
  Recursion error:
  maximum recursion depth exceeded while calling a Python object
  

  Running with verbosity gives a bit more hints into why the statemachine fails:

  [autodoc] from license_expression import AND
  [autodoc] import license_expression => <module 'license_expression' from '/home/stephan/Projects/license-expression/src/license_expression/__init__.py'>
  [autodoc] getattr(_, 'AND')
  [autodoc] => <class 'license_expression.AND'>
  [app] emitting event: 'autodoc-before-process-signature'(<function AND.__init__ at 0x7f2b01ff1dc0>, True)
  [app] emitting event: 'autodoc-process-signature'('class', 'license_expression.AND', <class 'license_expression.AND'>, {'members': <sphinx.ext.autodo
  [app] emitting event: 'autodoc-process-bases'('license_expression.AND', <class 'license_expression.AND'>, {'members': <sphinx.ext.autodoc._All ob
  [app] emitting event: 'autodoc-process-docstring'('class', 'license_expression.AND', <class 'license_expression.AND'>, {'members': <sphinx.ext.autodo
  [app] emitting event: 'autodoc-skip-member'('class', 'AND', <class 'license_expression.AND'>, False, {'members': <sphinx.ext.autodoc._All objec
  [app] emitting event: 'autodoc-skip-member'('class', 'FALSE', FALSE, False, {'members': <sphinx.ext.autodoc._All object at 0x7f2b03993f10>, 'un
  [app] emitting event: 'autodoc-skip-member'('class', 'NOT', <class 'boolean.boolean.NOT'>, False, {'members': <sphinx.ext.autodoc._All object a
  [app] emitting event: 'autodoc-skip-member'('class', 'OR', <class 'license_expression.OR'>, False, {'members': <sphinx.ext.autodoc._All object 
  [app] emitting event: 'autodoc-skip-member'('class', 'Symbol', <class 'license_expression.LicenseSymbol'>, False, {'members': <sphinx.ext.autod
  [app] emitting event: 'autodoc-skip-member'('class', 'TRUE', TRUE, False, {'members': <sphinx.ext.autodoc._All object at 0x7f2b03993f10>, 'undo
  [app] emitting event: 'autodoc-skip-member'('class', '__doc__', '\n    Custom representation for the AND operator to uppercase.\n    ', True, {
  [app] emitting event: 'autodoc-skip-member'('class', '__init__', <function AND.__init__ at 0x7f2b01ff1dc0>, True, {'members': <sphinx.ext.autod
  [app] emitting event: 'autodoc-skip-member'('class', '__module__', 'license_expression', True, {'members': <sphinx.ext.autodoc._All object at 0
  [autodoc] from license_expression import AND.AND
  

  And so on. But I still have no idea how this can be fixed. Maybe this is a bug created from boolean.py, as it happens with NOT as well, which is not defined as class in license-expression.

• The intersphinx mapping to boolean.py does not work. This is because it doesn't have an API via autodoc. Would be trivial to like here, but I suspect it will suffer from the same recursion problem as license-expression.

[pombredanne]

Thank you ++ !
Note that I also maintain boolean.py FWIW.
That said, I am a bit puzzled by this recursion issue
I wonder why autodoc would getattr(_, 'AND') which is at best arcane.
There is a bit of class hacking done with AND/OR/NOT but this could be a bug in autodoc too?

>>> from license_expression import AND
>>> import license_expression
>>> getattr(license_expression, 'AND')
<class 'license_expression.AND'>
>>> getattr(license_expression, 'AND') is AND
True
>>> license_expression
<module 'license_expression' from '/temp/le/venv/lib/python3.6/site-packages/license_expression/__init__.py'>
>>> _
<module 'license_expression' from '/temp/le/venv/lib/python3.6/site-packages/license_expression/__init__.py'>
>>> getattr(_, 'AND')
<class 'license_expression.AND'>

I cannot seem to reproduce this in a shell?

[stephanlachnit]

this could be a bug in autodoc too?

Tbh, I don't have enough knowledge about Python's inheritance to answer this question - thus I can't tell.

What confuses me is that autodoc works fine w/ boolean.py and in most of the license-expression classes except those that inherit from AND and OR from boolean.py and strangely license-expression.NOT, which isn't even part of class list?

[pombredanne]

This is great! Thank you ++