Nbless: Software Submission for Review

[marskar]

Submitting Author: Martin Skarzynski (@marskar)
All current maintainers: (@marskar)
Package Name: Nbless
One-Line Description of Package: Construct, deconstruct, convert, execute, & prepare slides from Jupyter notebooks
Repository Link: https://github.com/py4ds/nbless
Version submitted: 0.2.26
Editor: @lwasser
Reviewer 1: @ocefpaf
Reviewer 2: @kysolvik
Archive: N/A
JOSS DOI: N/A
Version accepted: TBD
Date accepted (month/day/year): 06/17/2019

---

Description

• Include a brief paragraph describing what your package does:

  The Nbless Python package allows you to
  - (de)construct,
  - convert,
  - execute, and
  - prepare slides from
  Jupyter notebooks.

  The Nbless Python package consists of 6 Python functions and shell commands:
  - nbconv, which converts a notebook into various formats.
  - nbdeck, which prepares a notebook to be viewed as or converted into slides.
  - nbexec, which runs a notebook from top to bottom and saves an executed version.
  - nbless, which calls nbuild and nbexec to create and execute a notebook.
  - nbraze, which extracts code and markdown files from a notebook.
  - nbuild, which creates a notebook from code and markdown files.

  For more on Nbless, please take a look at the official documentation.

Scope

• Please indicate which category or categories this package falls under:
  • Data retrieval
  • Data extraction
  • Data munging
  • Data deposition
  • Reproducibility
  • Geospatial
  • Education
  • Data visualization*

* Please fill out a pre-submission inquiry before submitting a data visualization package. For more info, see this section of our guidebook.

• Explain how and why the package falls under these categories (briefly, 1-2 sentences):

  Jupyter notebooks are important for reproducibility, because they facilitate literate programming, the combination of code and text.
  Literate programming is advantageous, because it allows descriptions of methods and results to be adjacent to the code used to obtain the results.
  I frequently use Jupyter notebooks in my work and in the Python classes I teach, but I often wish I could share small, simple files instead of large Jupyter notebooks.
  With Nbless, anyone can create Jupyter notebooks from simple source files or extract code and markdown files from Jupyter notebooks.
  In this way, Nbless supports round-trip conversion between source files and Jupyter notebooks. In other words, code and markdown files can be extracted from a Jupyter notebook AND then used to recreate the original Jupyter notebook.
  This can promote the modularity principle without sacrificing the benefits of literate programming or the convenience of a single file with all code, text, and output for the project.
  Code and markdown files can be easily be accessed with any text editor or even opened in a browser without an internet connection. Keeping source files makes version control simpler than trying to track changes made to Jupyter notebooks (see nbdime for another solution). Code files (.py, .R, etc.) are amenable to testing and linting, while notebooks are difficult to lint/test (see autopep8 and nbval).

• Who is the target audience and what are scientific applications of this package?

  The target audience is anyone who uses Jupyter notebooks. This package may help teachers and researchers to improve the efficiency of their Jupyter notebook workflows. One of the major features of Nbless is that it can facilitate the creation of slides from Jupyter notebooks. Jupyter slides can be converted in revealjs HTML files or viewed using nbviewer or RISE/Binder.
  I can imagine teachers and researchers writing markdown and code files and then using nbless to creating Jupyter notebooks to share with their students and colleagues.

• Are there other Python packages that accomplish the same thing? If so, how does yours differ?

  Related packages include:

  • pandoc
  • jupytext
  • notedown

  These packages can all convert Jupyter notebooks to other formats: markdown files (all three) or Python scripts (jupytext). Nbless wraps nbconvert to convert between file types, but it can do something all of the aforementioned packages cannot. Nbless can take a more modular approach to file conversion by extracting the contents of each notebook cell into a separate file (cell -> file) or using a source file to create each notebook cell (file -> cell). Looking beyond simple file conversion, Nbless includes a tool for making slides from notebooks (by setting slide_type in notebook metadata).

• If you made a pre-submission enquiry, please paste the link to the corresponding issue, forum post, or other discussion, or @tag the editor you contacted:

  The pre-submission inquiry link is Nbless: (de)construct, convert, execute, and prepare slides from Jupyter notebooks. #4

  I will close Nbless: (de)construct, convert, execute, and prepare slides from Jupyter notebooks. #4 as soon as I am done with Nbless: Software Submission for Review #7.

Technical checks

For details about the pyOpenSci packaging requirements, see our packaging guide. Confirm each of the following by checking the box. This package:

• does not violate the Terms of Service of any service it interacts with.
• has an OSI approved license
• contains a README with instructions for installing the development version.
• includes documentation with examples for all functions.
• contains a vignette with examples of its essential functions and uses.
• has a test suite.
• has continuous integration, such as Travis CI, AppVeyor, CircleCI, and/or others.

Publication options

• Do you wish to automatically submit to the Journal of Open Source Software? If so:

JOSS Checks

• The package has an obvious research application according to JOSS's definition in their submission requirements. Be aware that completing the pyOpenSci review process does not guarantee acceptance to JOSS. Be sure to read their submission requirements (linked above) if you are interested in submitting to JOSS.
• The package is not a "minor utility" as defined by JOSS's submission requirements: "Minor ‘utility’ packages, including ‘thin’ API clients, are not acceptable." pyOpenSci welcomes these packages under "Data Retrieval", but JOSS has slightly different criteria.
• The package contains a paper.md matching JOSS's requirements with a high-level description in the package root or in inst/.
• The package is deposited in a long-term repository with the DOI:

Note: Do not submit your package separately to JOSS

Are you OK with Reviewers Submitting Issues to your Repo Directly?

This option will allow reviewers to open smaller issues that can then be linked to PR's rather than submitting a more dense text based review. It will also allow you to demonstrate addressing the issue via PR links.

• Yes I am OK with reviewers submitting requested changes as issues to my repo. Reviewers will then link to the issues in their submitted review.

Code of conduct

• I agree to abide by pyOpenSci's Code of Conduct during the review process and in maintaining my package should it be accepted.

P.S. Have feedback/comments about our review process? Leave a comment here

Previous Repo: https://github.com/marskar/nbless/

[lwasser]

Editor checks:

• Fit: The package meets criteria for fit and overlap.
• Automated tests: Package has a testing suite and is tested via Travis-CI or another CI service. TRAVIS
• [x ] License: The package has an OSI accepted license MIT
• Repository: The repository link resolves correctly
• Archive (JOSS only, may be post-review): The repository DOI resolves correctly
• Version (JOSS only, may be post-review): Does the release version given match the GitHub release (v1.0.0)?

---

Editor comments

Thank you for this submission @marskar @ocefpaf and @leouieda will begin their review
Note: Martin is open to reviewers submitting issues to the repo directly. So please as you create your review, link to those issues if you create them

Reviewers: @ocefpaf @leouieda
Due date: 24 June 2019

@ocefpaf i'm suggesting a review deadline of June 24. It sounded like you wanted to do reviews one at a time. So @ocefpaf will submit his first and @leouieda ... will the two of you please coordinate on that? this is a new process so let's figure out what works best. also new is submitting issues directly rather than responding to a lot of text. A link to the reviewer template is below. I was thinking about adding readme checks to the reviewer template. please let me know what you think about that. i think it might make things easier!

Editor and review templates can be found here

[ocefpaf]

@lwasser, @leouieda and @marskar here is my review.
@marskar please feel free to ignore the checked items when copying this to answer and use only the unchecked ones. Also, every actionable item has an issue to the package repository linked, so feel free to answer there first and then summarize/cross-reference it here.

Package Review

Please check off boxes as applicable, and elaborate in comments below. Your review is not limited to these topics, as described in the reviewer guide

• As the reviewer I confirm that there are no conflicts of interest for me to review this work (If you are unsure whether you are in conflict, please speak to your editor before starting your review).

Documentation

The package includes all the following forms of documentation:

• A statement of need clearly stating problems the software is designed to solve and its target audience in README
• Installation instructions: for the development version of package and any non-standard dependencies in README
• Vignette(s) demonstrating major functionality that runs successfully locally
• Function Documentation: for all user-facing functions
• Examples for all user-facing functions
• Community guidelines including contribution guidelines in the README or CONTRIBUTING, and DESCRIPTION with URL, BugReports and Maintainer.

My suggestion is to reduce the overlap of the README with the documentation and make it more to the point: install and use examples (py4ds/nbless#16). There is one section in the docs that is quite confusioning and should probably be just an example of a workflow instead, with a link to the file (py4ds/nbless#15). The package reports two different version numbers (py4ds/nbless#12).

Functionality

• Installation: Installation succeeds as documented.
• Functionality: Any functional claims of the software been confirmed.

I found two minor problems when trying to run the CLI as the docs recommend:

• The docs mention two ways for converting to HTML but only one works py4ds/nbless#14

• nbexec behavior is different from the docs py4ds/nbless#13

• Performance: Any performance claims of the software been confirmed.

• Automated tests: Tests cover essential functions of the package and a reasonable range of inputs and conditions. All tests pass on the local machine.

Test covers only 2 out of 6 main functions (py4ds/nbless#17).

• Continuous Integration: Has continuous integration, such as Travis CI, AppVeyor, CircleCI, and/or others.
• Packaging guidelines: The package conforms to the pyOpenSci packaging guidelines.

---

Review Comments

The package is a good fit for PyOpenSci. The documentation could use some polishing, the CLI examples are good but the rest is a bit terse to read. I believe that one of the functionality issues I found may be due to documentation problems and not really a bug (py4ds/nbless#13).

The repository does not have a community guidelines. (Note to PyOpenSci: do we have examples of those to point people to?)

Both development and standard installations were easy and all the tests passed. My doubt is regarding the pandoc dependency declared on the CI. Pandoc is optional in nbconvert but I know that some results may be different if you have it present. Does nbless expect pandoc for some features? if so are those tested properly? The tests passes without it BTW but I found this comment and I could not find a test against the expected output.

[marskar]

Thanks for the very helpful review @ocefpaf!
I plan to work through each of the 6 issues before the end of the week.

In the meantime, the answer to your question regarding pandoc is that the nbconv function/command (a wrapper for jupyter nbconvert) requires pandoc for conversion to all formats other than HTML. Converting to PDF also requires LaTeX. I will make sure to include this in the docs.
The nbconv tests that you linked to are commented out, because I had trouble satisfying the pandoc dependency in my Travis build. I will try to figure out how to get pandoc and Travis to cooperate.

[marskar]

• I set up my versioning system correctly
• I fixed my travis testing problem (turns out the problem was with tox)
• I added many tests
• I made sure the behaviour of the nbconv matches the docs
  The remaining issues all have to do with the docs.
  I will try to wrap this up this week.