Custom docstring ignore tag

[dougthor42]

This allows the user to customize the docstring ignore separator.

The custom separator is set during blueprint initialization:

blp = Blueprint('foo', __name__, docstring_sep="~~~")
@blp.route('/', methods=['GET'])
def view_func():
    """Summary
    
    Descr
    ~~~
    This line and more ignored.
    """
    return "foo"

## Results in:
# summary: "Summary"
# description: "Descr"

blp = Blueprint('foo', __name__, docstring_sep=None)
@blp.route('/', methods=['GET'])
def view_func():
    """Summary
    
    Descr
    ~~~
    This line is included.
    """
    return "foo"

## Results in:
# summary: "Summary"
# description: "Descr\n~~~\nThis line is included."

Fixes #49.

[coveralls]

Coverage remained the same at 100.0% when pulling a965505 on dougthor42:custom-docstring-ignore-tag-gh49 into 5434725 on Nobatek:master.

[lafrech]

Thanks for the PR.

Code looks good.

Regarding the test, I'd prefer a minimalist test that tests each case (explicit None, default "---" and custom string) on a dummy ad-hoc docstring. Real-life examples are nice but I don't think it is worth 100 lines of code in this case.

[dougthor42]

• Is this where you were thinking of adding the arg?
• Where are the docs for the Blueprint so that I can add it there?

[lafrech]

I was thinking of making it a class attribute the user could override in a subclass, like HTTP_METHODS.

class Blueprint:

    DOCSTRING_SEP = '---'

I'd document this in docs/openapi.rst.

[dougthor42]

Do you still want me to move it to a class attribute rather than (or in addition to) an initialization arg?

[lafrech]

Class attribute only would be consistent with the rest of the lib.

The separator will most probably be something the user will use consistently in all his Blueprints so subclassing and using a class attribute seems nice to me.

description is obviously different because it differs in all instances.

[dougthor42]

Sounds good. I added it as a class attribute.

I also left the initialization arg so that users can do any of these:

# No need to subclass
blp0 = Blueprint('test', __name__, url_prefix='test', docstring_sep="~~~")

# But you can if you want to
class MyBlueprint(Blueprint):
    DOCSTRING_SEP = "~~~"

blp1 = MyBlueprint('test', __name__, url_prefix='test')

# and you can still override your subclass on a per-instance bases if desired.
blp2 = MyBlueprint('test', __name__, url_prefix='test', docstring_sep="^^^")

If that's not to your liking please let me know and I'll remove the init arg completely.

[dougthor42]

Regarding the test, I'd prefer a minimalist test that tests each case (explicit None, default "---" and custom string) on a dummy ad-hoc docstring. Real-life examples are nice but I don't think it is worth 100 lines of code in this case.

OK, I'll change that. Do you want to keep everything in that single test case with multiple asserts? Or would you rather a new test function for each? Eg:

def test_load_from_docstring_default_sep():
def test_load_from_docstring_custom_sep():
def test_load_from_docstring_none_sep():

---

Other questions:

1. Do you have any preferences on squashing? If not, I'll rebase/squash this into 2 commits:
   1. the change to load_info_from_docstring and related tests
   2. the change to the Blueprint class and related tests
2. Do you want the changelog update as part of this MR? If so, what would you like? (I don't see an "unreleased" section or anything like that.) Or will you handle the changelog update?
3. Where else do docs need to be updated?

[lafrech]

Can't you access self.docstring_sep in store_method_docs itself?

[dougthor42]

No, at least not with the base I'm working from. store_method_docs is defined within Blueprint._store_endpoint_docs and does not accept the instance as an arg.

My current base is a1c2dfc, v0.15.0.

[lafrech]

I'm not familiar with closures. I thought self would be accessible since it is defined in the scope of Blueprint._store_endpoint_docs where store_method_docs is defined.

Currently out of office, I'll try to check this and the rest when I come back.

[lafrech]

OK, I'll change that. Do you want to keep everything in that single test case with multiple asserts? Or would you rather a new test function for each?

I don't really mind. But thanks for asking.

Do you have any preferences on squashing? If not, I'll rebase/squash this into 2 commits:

• the change to load_info_from_docstring and related tests
• the change to the Blueprint class and related tests

That's perfect.

Do you want the changelog update as part of this MR? If so, what would you like? (I don't see an "unreleased" section or anything like that.) Or will you handle the changelog update?

Don't bother. I can do it.

I generally don't create an "unreleased" section. I just add the next version when needed.

Where else do docs need to be updated?

I think updating relevant section in docs/openapi.rst (https://github.com/Nobatek/flask-rest-api/blob/master/docs/openapi.rst#add-summary-and-description) is enough.

Thanks. Sorry for the delay...

[lafrech]

Rebased, squashed (perhaps a little too much) and reworked. Let's merge.