Repository navigation
Docstring format #107
Description
From Igor Novozhilov (@IgorNovozhilov) on April 24, 2017 8:20
Hi, I have a question.
What is the documentation standard parameters supported for mo method?
At first I thought it was NumPy, but I have that kind of problem:
But the standard itself is described without spaces to describe the parameters and types:
http://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_numpy.html
Copied from original issue: DonJayamanne/pythonVSCode#908
Activity
DonJayamanne commentedon Nov 13, 2017
Igor Novozhilov (@IgorNovozhilov)
Apologies for not getting back to you on this. Been focusing on more critical issues and in the process managed to over look simple items. I'll try to look into this sometime this month.
DonJayamanne commentedon Nov 13, 2017
From Josh Kitchens (@BlacKCaT27) on October 23, 2017 20:36
Don,
If you can maybe point me in the general direction of where to start for resolving this and adding support, I can at least start exploring potential solutions if you're tied up on other things. I would definitely love to have proper docstring formatting support, and would love to help get there.
DonJayamanne commentedon Nov 13, 2017
All of the magic takes place here https://github.com/DonJayamanne/pythonVSCode/blob/master/src/client/providers/jediHelpers.ts#L51
Josh Kitchens (@BlacKCaT27) thanks for volunteering to help in this space.
I think as a first step, I'd like to identify the formats of doc string(s) you intend on adding support for.
There's no point in supporting all formats under the sun, just a maintenance nightmare.
DonJayamanne commentedon Nov 13, 2017
From Josh Kitchens (@BlacKCaT27) on October 24, 2017 14:20
This might be a bit overkill, but in my head I'm thinking of a small abstraction layer on top of the various formats. If we identify the total set of features offered by these formats (section headers, code blocks, lists, etc), it should be a relatively simple task to restructure the code to identify and apply features to the markdown based on a user-configured format setting (using reST as the default since that implementation already appears to mostly exist).
Going this route, we could easily add support for additional formats by simply creating a format-specific implementation class for the feature-set then injecting them into the jediHelper at runtime.
In terms of initially supported formats, my vote would be to start with reST since that's already there and would just need to be refactored, and additionally google docstring formatting support since that spec is relatively popular and clearly defined/documented.
DonJayamanne commentedon Nov 13, 2017
From Josh Kitchens (@BlacKCaT27) on October 24, 2017 14:33
Also, I've noticed a similar issue which I'm commenting here as it's related to the exact same root cause (bad formatting handling): escape characters are not being handled properly. Example:
docstring text:
SaveSimulation(r'E:\aSimFile.sim') and SaveSimulation('E:\aSimFile.sim') will work, while just SaveSimulation('E:\aSimFile.sim')
tooltip displays:
SaveSimulation(r'E�SimFile.sim') and SaveSimulation('E \aSimFile.sim') will work, while just SaveSimulation('E:�SimFile.sim')
I'll have to dig into the format specifications more to see if they call out specific details around escape sequences, but my 'gut feeling' is that they should be treated as regular characters and not be escaped without some sort of explicit markup instructing the formatter to do so.
brettcannon commentedon Nov 14, 2017
Closing as a duplicate of DonJayamanne#38