search

jupyter / nbformat

Reference implementation of the Jupyter Notebook format
http://nbformat.readthedocs.io/
BSD 3-Clause "New" or "Revised" License
265 stars 152 forks source link

Missing documentation #219

Open ghazpar opened 3 years ago

ghazpar commented 3 years ago

For the latest version of the documentation (for nbformat 5.1.3), the following is either lacking or missing:

  1. nbformat.v4.upgrade is not documented, but very useful for upgrading to the latest minor version of the v4 format. Notably, I was having the issue of adding new cells to a notebook using the 4.2 format, which made the notebook format invalid, because the different v4.new_cell methods adds a cell id which is incompatible with the <4.5 formats, and there is no way to specify a minor version when adding new cells.
  2. nbformat.v4.upgrade returns the upgraded notebook whenever the notebook is modified, but returns None otherwise. Based on the least surprise principle, this is not the best strategy in my opinion. It would be better to always return the notebook, or at least to make this behavior explicit in the documentation.
  3. The arguments of the nbformat.validate method are not currently documented, and some of them are not obvious.