Add class for block of strings inside docstring #4
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This should make the protect against testing against the current directory rather than the installed package
1. Add environment specifically for linters (black, pydocstring, import-order, pep8 naming, bandit, flake8, pylint) 2. Add config for linters 3. Fix import orders 4. Fix missing docstring 5. Fix elif statements with raise statement
Branch was not getting covered because generator was not being exhausted. That's not an issue because only the first entry is interesting
1. Remove DocContent.make_numpy_docstring, DocContent.make_google_docstring, DocContent.make_rst_docstring 2. Add DocContent.make_docstring that calls the correct method for the given style via name of the method 3. Change name of the methods from make_numpy_docstring to make_docstring_numpy, from make_numpy_docstring_signature to make_docstring_numpy_signature, from make_google_docstring to make_docstring_google, and from make_rst_docstring to make_docstring_rst. Having multiple abstract methods in DocSection for different styles of docstring seems to get more complicated as the number of styles increases. If the goal is to make it easier to create docstrings of new styles, then we can just add more styles to the subclasses without having to add more functions at the base class. I'm not 100% sure that the best way is to keep adding methods for each style (this would result in the class growing quite quickly). Maybe it'd be better to organize the modules by the styles also i.e. make a subclass for each child of DocSection specific for the style.
1. Remove DocContent.__init__ 2. Create Empty class for testing in the module rather than in test functions. It seems that an abstract __init__ doesn't really do much except for preventing any initialization. Though it does serve a purpose, it seems to complicate the code more than it adds anything
1. Remove `default_style` 2. Format strings 3. Remove docstrings and tests for default_style At the moment, it does not seem necessary to add an attribute does nothing except to store the default value. This may be useful for making some porcelain later, but it is not ncessary at the moment.
1. Tweak napoleon's parsers to return docinstance compatible objects 2. Add NumpyDoc parser for see also section. Copied from napoleon's copy 3. Add new description for entries of see also section 4. Add numpy's special docstring for see also 5. Add test 6. Skip tests for napoleon 7. Add extra installations for napoleon Time: 7h
Before, Docstrings/DocSection could handle strings by treating them specially when the docstring was being created. Normally, blocks of strings were separately from one another with two newlines wrapped to the appropriate weight and indented according to user input. However, it seems that sometimes (e.g. in References or See Also sections) it is necessary to separate out the string blocks with different number of newlines. Instead of adding a new parameter, a new class for the string blocks were created, to be consistent with the rest of the code. 1. Add DocParagraph class 2. Add tests Time: 2h
1. Remove support for string content in DocSection 2. Replace strings in test with DocParagraph 3. Remove string formatting inside make_docstring's Time: 2h
It seems possible that the make_docstring for a specific style (see `DocParagraph.make_docstring_rst`) have keyword arguments outside of those defined in `DocContent.make_docstring`). This commit supports passing the keyword arguments.
Since DocParagraph is used interchangeably with str, it would be nice to compare theses objects directly to string rather than instances of DocParagraph Time: 0.5h
Turns out removing string support causes a lot of the tests to break, so it would be better to actually support strings in DocSection (and rest of the code). In fact, it is more intuitive to be able to use strings anyways. Internally, DocSection still uses DocParagraph, but upon intialization, strings are converted to DocParagraph
1. Convert internal components of Summary to use Docparagraph instead of string
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Before, strings were treated separately inside
DocstringandDocSection. Now, the added class can be used to represent these strings so that we don't need to treat these structures separatelyDepends on PR #2 (includes PR#3)