MAINT: Get docs to build again #384
Conversation
corranwebster
left a comment
corranwebster
left a comment
There was a problem hiding this comment.
Some changes which really shouldn't have been reverted from the point of view of Python 2.7. Fixing is optional.
What would the work be to eg. get rid of Numpydoc in favour of Napoleon?
Similarly what would the work level be to get rid of the Traits documenter in favour of traits.util.trait_documenter or https://github.com/enthought/trait-documenter (not sure which is currently preferred).
docs/source/sphinxext/docscrape.py
Outdated
| if self._role: | ||
| if self._role not in roles: | ||
| print("Warning: invalid role %s" % self._role) | ||
| if not roles.has_key(self._role): |
There was a problem hiding this comment.
This seems an unnecessary change.
docs/source/sphinxext/docscrape.py
Outdated
| argspec = argspec.replace('*','\*') | ||
| signature = '%s%s' % (func_name, argspec) | ||
| except TypeError as e: | ||
| except TypeError, e: |
There was a problem hiding this comment.
Don't revert this line!
docs/source/sphinxext/docscrape.py
Outdated
| #print("Docstring follows:") | ||
| #print(doclines) | ||
| #print('='*78) | ||
| except ValueError, e: |
docs/source/sphinxext/numpydoc.py
Outdated
| else: | ||
| return sys.modules[modname] | ||
| except (ValueError, ImportError, AttributeError, KeyError) as e: | ||
| except (ValueError, ImportError, AttributeError, KeyError), e: |
|
Thanks Corran. Just for the record, the reverts were done completely mechanistically. I'd rather not touch this part of the codebase for the time being; I agree that using standard Sphinx plugins like Napoleon and the Traits documenter (which were probably not around when this code was originally written) is the way forward. |
MAINT: Get docs to build again
2 participants
To get the docs build back on the rails (#380), I reverted the Python 2/3 compatibility layer from #369 for the Sphinx extensions (the rest of the compatibility layer is still in place). I began by updating the import statements to match what Sphinx expects, but even after doing this I found that some of the six constructs didn't play well with the rest of the code. As this code is old and will not work on Python 3 without some serious maintenance (#324), I decided to just roll back that part of the code.
closes #380