Update docstrings/pydoc/help (#170) #438

gabrielkrell · 2017-10-25T08:00:56Z

Add docstrings in main package, helpers. Now things will show up nicely when people show documentation in their editor, use help, or use pydoc to browse the documentation in HTML form.

Downside: much of the Mail helper docs are copied from the v3 docs, which isn't great for maintainability. I think it'd be too unapproachable just to say "read the docs", and linking docs updates to these docstrings would be a lot of work for the rewards. Maybe a future automation candidate though :)

Example output:

Pop-up docs in editors:

pydoc HTML:

Package-level help:

>>> import sendgrid
>>> help(sendgrid)
Help on package sendgrid:

NAME
    sendgrid

DESCRIPTION
    This library allows you to quickly and easily use the SendGrid Web API v3 via
    Python.

    For more information on this library, see the README on Github.
        https://github.com/sendgrid/sendgrid-python
    For more information on the SendGrid v3 API, see the v3 docs:
        http://sendgrid.com/docs/API_Reference/api_v3.html
    For the user guide, code examples, and more, visit the main docs page:
        http://sendgrid.com/docs/index.html

    Available subpackages
    ---------------------
    helpers
        Modules to help with common tasks.

PACKAGE CONTENTS
    helpers (package)
    sendgrid
    version
-- More  --

And individual classes:

>>> from sendgrid.helpers.mail import Mail
>>> help(Mail)
Help on class Mail in module sendgrid.helpers.mail.mail:

class Mail(builtins.object)
 |  A request to be sent with the SendGrid v3 Mail Send API (v3/mail/send).
 |
 |  Use get() to get the request body.
 |
 |  Methods defined here:
-- More  --

Add pydoc for package. I don't want to duplicate the REAME here, so directing users to it instead. HTTPS doesn't get highlighted for some reason, so HTTP link used.

Some copied from config.yml.

These are sphinx style, but it takes up a lot of space.

Still a few to go.

Apparently Sphinx can do list(type) or list[type]. If we ever use it this'll make things more clear.

Add docstrings for methods, properties. Typo fix in Mail.send_at

Whew, almost done.

These don't really add anything over the class docstrings, but they're also the thing that most people will look at.

Can't use these in Python 2 because we haven't declared an encoding. Oops.

codecov-io · 2017-10-25T08:05:49Z

Codecov Report

Merging #438 into master will decrease coverage by 0.08%.
The diff coverage is 0%.

@@            Coverage Diff             @@
##           master     #438      +/-   ##
==========================================
- Coverage      83%   82.92%   -0.09%     
==========================================
  Files          30       30              
  Lines        1024     1025       +1     
  Branches      160      161       +1     
==========================================
  Hits          850      850              
- Misses         84       85       +1     
  Partials       90       90

Impacted Files	Coverage Δ
sendgrid/helpers/mail/section.py	`85.71% <ø> (ø)`	⬆️
sendgrid/helpers/mail/mail_settings.py	`87.5% <ø> (ø)`	⬆️
sendgrid/helpers/mail/bcc_settings.py	`83.33% <ø> (ø)`	⬆️
sendgrid/helpers/inbound/__init__.py	`100% <ø> (ø)`	⬆️
sendgrid/helpers/mail/asm.py	`73.91% <ø> (ø)`	⬆️
sendgrid/helpers/mail/sandbox_mode.py	`85.71% <ø> (ø)`	⬆️
sendgrid/helpers/mail/mail.py	`97.51% <ø> (ø)`	⬆️
sendgrid/helpers/mail/header.py	`85.71% <ø> (ø)`	⬆️
sendgrid/helpers/mail/tracking_settings.py	`96.96% <ø> (ø)`	⬆️
sendgrid/helpers/inbound/app.py	`73.91% <ø> (ø)`	⬆️
... and 18 more

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 35cc980...c64d7fd. Read the comment docs.

mbernier · 2017-10-27T04:07:28Z

You, sir, are an animal.

mbernier · 2017-10-27T04:07:52Z

sendgrid/helpers/inbound/send.py

-print(response.headers)
-print(response.body)
+
+if __name__ == '__main__':


This isn't a doc string! Looks like this snuck in?

Oops, forgot to document that. pydoc imports files to get their docstrings, so the unconditional code there executes and causes an error since it isn't in the right context. I added an escape so that it just imports and doesn't attempt to do anything unless it's being run directly or from the command line.

Shuffle docs around to fit the new Mail helper structure. Hopefully I didn't miss anything; due to the amount of code getting moved around. I'll check the diff against master and then revert if needed.

Clear up some straggling stray whitespace, etc.

Put TrackingSettings in the right place.

gabrielkrell · 2017-10-29T02:42:02Z

I wish codeclimate didn't look at docstrings - they're repetitive by nature, resulting in a lot of errors. @mbernier, resolved merge conflicts from #472.

mbernier · 2017-10-29T03:46:10Z

I think we can configure the docstring problem at codeclimate, it is running on an extremely simplified config - https://github.com/sendgrid/sendgrid-python/blob/master/.codeclimate.yml This can be updated, but I didn't look into it yet.

mbernier · 2017-10-29T03:47:25Z

I am not sure if this is related to this PR, but I am getting an error in Travis after it runs tests:

  File "/home/travis/build/sendgrid/sendgrid-python/test/test_mail.py", line 410, in test_kitchenSink

more info

gabrielkrell · 2017-10-29T04:07:15Z

I made an issue (#483) for the Code Climate thing (not a big deal IMO, maybe a good last-minute Hacktoberfest) and will look at the Travis stuff.

I hate moving around big chunks of code like this; I wish git was more intelligent moving things between files.

mbernier · 2017-10-30T03:20:35Z

@gabrielkrell let me know when you're g2g on this one :)

gabrielkrell · 2017-10-30T03:21:42Z

@mbernier I think we're all set. Excited to see this in master.

thinkingserious · 2017-10-30T17:46:13Z

Hello @gabrielkrell,

Thanks again for the PR!

We want to show our appreciation by sending you some swag. Could you please fill out this form so we can send it to you? Thanks!

Team SendGrid DX

gabrielkrell added 11 commits October 22, 2017 16:49

Add top-level pydoc

6afcf7d

Add pydoc for package. I don't want to duplicate the REAME here, so directing users to it instead. HTTPS doesn't get highlighted for some reason, so HTTP link used.

Add docstrings: Inbound Parse helper

0ee7cda

Some copied from config.yml.

Add Mail top-level docstring

d285843

Add docstrings to utility classes

a819394

These are sphinx style, but it takes up a lot of space.

Add Mail() docstrings

062c4f2

Still a few to go.

Fix return types

a139826

Apparently Sphinx can do list(type) or list[type]. If we ever use it this'll make things more clear.

Add Personalization, TrackingSetings, MailSettings docstrings

c26f675

Add docstrings for methods, properties. Typo fix in Mail.send_at

Merge remote-tracking branch 'upstream/master' into pydoc-update

6ebf12e

Main docstrings

4f546e1

Whew, almost done.

Add init docstrings

d140594

These don't really add anything over the class docstrings, but they're also the thing that most people will look at.

Remove smart quotes

a1466e1

Can't use these in Python 2 because we haven't declared an encoding. Oops.

thinkingserious added the status: code review request requesting a community code review or review from Twilio label Oct 25, 2017

mbernier reviewed Oct 27, 2017

View reviewed changes

mbernier added difficulty: hard fix is hard in difficulty hacktoberfest labels Oct 27, 2017

gabrielkrell mentioned this pull request Oct 28, 2017

Error-checking in Mail helper/ASM #413

Merged

gabrielkrell added 3 commits October 28, 2017 21:24

Merge remote-tracking branch 'upstream/master' into pydoc-update

4d9b68d

Shuffle docs around to fit the new Mail helper structure. Hopefully I didn't miss anything; due to the amount of code getting moved around. I'll check the diff against master and then revert if needed.

PEP fixes

1507bba

Clear up some straggling stray whitespace, etc.

Fix careless merge

b84356a

Put TrackingSettings in the right place.

Fix more broken merge stuff

c64d7fd

I hate moving around big chunks of code like this; I wish git was more intelligent moving things between files.

mbernier merged commit f1933ff into sendgrid:master Oct 30, 2017

thinkingserious added the hacktoberfest label Oct 30, 2017

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Update docstrings/pydoc/help (#170) #438

Update docstrings/pydoc/help (#170) #438

gabrielkrell commented Oct 25, 2017

codecov-io commented Oct 25, 2017 •

edited

Loading

mbernier commented Oct 27, 2017

mbernier Oct 27, 2017

gabrielkrell Oct 28, 2017 •

edited

Loading

gabrielkrell commented Oct 29, 2017

mbernier commented Oct 29, 2017

mbernier commented Oct 29, 2017

gabrielkrell commented Oct 29, 2017 •

edited

Loading

mbernier commented Oct 30, 2017

gabrielkrell commented Oct 30, 2017

thinkingserious commented Oct 30, 2017

Update docstrings/pydoc/help (#170) #438

Update docstrings/pydoc/help (#170) #438

Conversation

gabrielkrell commented Oct 25, 2017

Example output:

codecov-io commented Oct 25, 2017 • edited Loading

Codecov Report

mbernier commented Oct 27, 2017

mbernier Oct 27, 2017

Choose a reason for hiding this comment

gabrielkrell Oct 28, 2017 • edited Loading

Choose a reason for hiding this comment

gabrielkrell commented Oct 29, 2017

mbernier commented Oct 29, 2017

mbernier commented Oct 29, 2017

gabrielkrell commented Oct 29, 2017 • edited Loading

mbernier commented Oct 30, 2017

gabrielkrell commented Oct 30, 2017

thinkingserious commented Oct 30, 2017

codecov-io commented Oct 25, 2017 •

edited

Loading

gabrielkrell Oct 28, 2017 •

edited

Loading

gabrielkrell commented Oct 29, 2017 •

edited

Loading