Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[MRG] Refactor argparse #129

Merged
merged 6 commits into from
Mar 20, 2019
Merged

Conversation

jasmainak
Copy link
Contributor

This PR builds on top of #126 (to avoid rebasing troubles) -- it's why the diff is large. Once that is merged into master, the diff wouldn't look so bad. It's separating the argument parsing from the actual nuts and bolts of jupyter-book. This has two advantages that I can clearly see:

  • easier to debug when testing. The traceback will make more sense and it will be possible to use postmortem debugging with --pdb
  • the code coverage will be correct. At the moment, it shows 0% for all the files

I just did it for build.py at the moment, but if it's useful I can do it for all the files.

@jasmainak
Copy link
Contributor Author

okay rebased so that the diff looks more reasonable. Should I continue for the other files?

@choldgraf
Copy link
Collaborator

@jasmainak nice job! thanks for pushing this through :-) I'm +1 on doing something like this with the other main CLI functions as well. I think it'll make things more modular and easier to test!

@jasmainak jasmainak force-pushed the refactor_argparse branch 3 times, most recently from e5ab087 to e243950 Compare March 15, 2019 04:19
@jasmainak
Copy link
Contributor Author

@choldgraf you might want to start reviewing already so that the work is distributed and the PR doesn't stay open for too long and I become sad. maybe @emdupre can also review? :)

@@ -242,17 +219,15 @@ def upgrade_book():
try:
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not a big fan of try statements ...

errors pass silently if you have them

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

though in this case we're capturing errors and displaying a custom error message at the end if we run into the errors, no?

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This seems like an reasonable try/except block to me, but would be really interested in how you think it could be improved @jasmainak !

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It was my priors commenting rather than the posterior :-P But wouldn't you hide problems in the upgrade if you use such a block? Imagine a user has a problem upgrading. When you ask them for the traceback, they won't have one because it's been caught and instead you will get the print statement -- which is not so useful for debugging.

@jasmainak
Copy link
Contributor Author

@choldgraf codecov is not working. Are you sure you enabled it?

@jasmainak jasmainak marked this pull request as ready for review March 15, 2019 04:23
@jasmainak jasmainak changed the title Refactor argparse WIP: Refactor argparse Mar 15, 2019
@choldgraf
Copy link
Collaborator

hey @jasmainak, sorry, I've been at the Jupyter annual community meeting all week in Washington DC, so haven't gotten any work done. I have a flight back to SF this evening, will try giving this a review on the flight if I can get wifi

@emdupre
Copy link
Collaborator

emdupre commented Mar 15, 2019

Reviewing this is on my to-do list for this weekend -- Looking forward to having a chance to sit down with it ✨ Thanks for the work so far, @jasmainak !

@choldgraf
Copy link
Collaborator

(also just a note @jasmainak , in general I don't review PRs if they have "WIP" in the title unless explicitly asked to. To me WIP means "please don't look closely yet because I might change stuff in the near future")

Copy link
Collaborator

@choldgraf choldgraf left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This looks much cleaner @jasmainak , thanks so much! It all seems pretty reasonable to me, I like splitting off the "commands" into its own module. I had a couple small comments in there, but I think as long as tests are happy then I am happy with this step.

I won't "approve" since this is still marked as WIP, happy to look at something specific if you like.

jupyter_book/create.py Outdated Show resolved Hide resolved
@@ -242,17 +219,15 @@ def upgrade_book():
try:
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

though in this case we're capturing errors and displaying a custom error message at the end if we run into the errors, no?

jupyter_book/commands/__init__.py Show resolved Hide resolved
@jasmainak
Copy link
Contributor Author

jasmainak commented Mar 15, 2019 via email

@choldgraf
Copy link
Collaborator

From my first pass above, it didn't seem like there was too much complexity being added, no? You're basically rearranging what is there rather than adding something new yeah? I think this makes it much easier to review because you're basically just doing a much better job of building a CLI than I did in my first pass :-)

Co-Authored-By: jasmainak <jasmainak@users.noreply.github.com>
@choldgraf
Copy link
Collaborator

This LGTM! @emdupre do you wanna take a look before we merge?

@jasmainak jasmainak changed the title WIP: Refactor argparse [MRG] Refactor argparse Mar 16, 2019
@emdupre
Copy link
Collaborator

emdupre commented Mar 16, 2019

I can look tomorrow, but if you're happy with everything @choldgraf feel free to merge now :)

@jasmainak
Copy link
Contributor Author

jasmainak commented Mar 16, 2019

okay, so I think I'm done here. I didn't touch generate_toc.py as it seems to be bundled with the template jupyter book and I'm not quite sure what's going on there.

please do test it locally though. There aren't many unit tests in the repo -- hence I highly recommend testing it before merging :)

@choldgraf
Copy link
Collaborator

choldgraf commented Mar 16, 2019

ok cool, so tomorrow next week because we all value work-life balance ;-) @emdupre and I do a little local demo and see if we can break something :-)

@jasmainak
Copy link
Contributor Author

because we all value work-life balance

are you holidaying in France again????! :-)

Copy link
Collaborator

@emdupre emdupre left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This looks great ! Very easy to read, now 👍 I had a few questions about docstrings and how we're using argparse, but really excited about this ! ✨

jupyter_book/build.py Show resolved Hide resolved
###############################################
# Default values and arguments

args = parser.parse_args(sys.argv[2:])
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Duplicate of L51 ?

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Instead of writing to args can we just set dest for each of the options ?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

hmm ... does dest allow you to avoid parser.parse_args? I thought dest is inferred from the option string so you don't need to specify it

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sorry, I shouldn't have used dest. I was thinking something like:

args = parser.parse_args(sys.argv[2:])
new_book(**vars(args))

Also, multiple variables are set from toc here, and it looks like we have verbose twice !

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's really neat! But here, we have a couple of variables that shouldn't be passed as is. Perhaps something to iterate in future PRs?

Also, that was a good catch! The fact that the tests pass indicate that the tests should be improved.

jupyter_book/commands/create.py Outdated Show resolved Hide resolved
jupyter_book/create.py Show resolved Hide resolved
@@ -242,17 +219,15 @@ def upgrade_book():
try:
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This seems like an reasonable try/except block to me, but would be really interested in how you think it could be improved @jasmainak !

toc = yaml.load(ff.read())

# Drop divider items and non-linked pages in the sidebar, un-nest sections
toc = _prepare_toc(toc)

###############################################################################
################################################
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@choldgraf just trying to slowly make it more pep8 compliant :) So we can remove the ignore for the 80 line rule eventually ...

@jasmainak
Copy link
Contributor Author

Thanks @emdupre for the review! I addressed all of them save one. I'll reply to that specific comment in a moment.

@choldgraf this PR made me realize that you also need an API page. Different functions take different variable names and there are some inconsistencies. But I would leave it for another PR.

Copy link
Collaborator

@choldgraf choldgraf left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I just tried pulling @jasmainak 's branch and the books built well for me + tests pass, I agree with @emdupre that this is much more understandable, and the code LGTM. I'm +1 on merge, feel free to hit the green button @emdupre

@emdupre
Copy link
Collaborator

emdupre commented Mar 20, 2019

Sorry I'm so slow to respond on these -- I'm finishing up writing my dissertation proposal so things are a little busy at the moment 😞

I made one more comment but feel free to merge without addressing if we want to iterate later. I think this is a huge improvement and don't want to hold it up because of my lateness ! Thanks again @jasmainak

parser.add_argument("--custom-css", default=None,
help="A path to a CSS file that defines some custom CSS rules for your book")
parser.add_argument("--custom-js", default=None,
help="A path to a JS file that defines some custom CSS rules for your book")
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@choldgraf this seemed like an awkward help statement to me. But I let it be as such because I don't know the inner workings of jupyter-book yet. Why would a JS file define CSS rules?

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

oops, this should be "JS" not "CSS"!

Suggested change
help="A path to a JS file that defines some custom CSS rules for your book")
help="A path to a JS file that defines some custom JavaScript code for your book")

@choldgraf
Copy link
Collaborator

@jasmainak if you accept my suggestion let's merge this thing! :-)

@jasmainak
Copy link
Contributor Author

I can't accept. Github tells me I can't accept a suggestion on a deleted line :)

@choldgraf
Copy link
Collaborator

ok, I opened #146 to keep track of the CLI problems :-)

:shipit::shipit: :shipit: :shipit: :shipit: :shipit: :shipit: :shipit: :shipit: :shipit: :shipit: :shipit:

thanks for the awesome patch @jasmainak - should make things easier to improve and iterate on!

@choldgraf choldgraf merged commit ba004e1 into jupyter-book:master Mar 20, 2019
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants