upstream/ipython Commit - r10042:699a45a9

Merge pull request from dwyde/improve-notebook-js-yuidoc...

Matthias Bussonnier -

r10042:699a45a9

parent child

IPython/frontend/html/notebook/static/js/README.md

0 +1 -1

              ```bash
              cd IPython/frontend/html/notebook/static/js/
              # install yuidoc
-             npm install yuidoc
+             npm install yuidocjs
              ```

IPython/frontend/html/notebook/static/js/notebook.js

0 +423 -56

                  var utils = IPython.utils;
                  var key   = IPython.utils.keycodes;
+                 /**
+                  * A notebook contains and manages cells.
+                  *
+                  * @class Notebook
+                  * @constructor
+                  * @param {String} selector A jQuery selector for the notebook's DOM element
+                  * @param {Object} [options] A config object
+                  */
                  var Notebook = function (selector, options) {
                      var options = options || {};
                      this._baseProjectUrl = options.baseProjectUrl;
                      this.bind_events();
                  };
+                 /**
+                  * Tweak the notebook's CSS style.
+                  *
+                  * @method style
+                  */
                  Notebook.prototype.style = function () {
                      $('div#notebook').addClass('border-box-sizing');
                  };
+                 /**
+                  * Get the root URL of the notebook server.
+                  *
+                  * @method baseProjectUrl
+                  * @return {String} The base project URL
+                  */
                  Notebook.prototype.baseProjectUrl = function(){
                      return this._baseProjectUrl || $('body').data('baseProjectUrl');
                  };
+                 /**
+                  * Create an HTML and CSS representation of the notebook.
+                  *
+                  * @method create_elements
+                  */
                  Notebook.prototype.create_elements = function () {
                      // We add this end_space div to the end of the notebook div to:
                      // i) provide a margin between the last cell and the end of the notebook
                      $('div#notebook').addClass('border-box-sizing');
                  };
+                 /**
+                  * Bind JavaScript events: key presses and custom IPython events.
+                  *
+                  * @method bind_events
+                  */
                  Notebook.prototype.bind_events = function () {
                      var that = this;
                      });
                  };
+                 /**
+                  * Scroll the top of the page to a given cell.
+                  *
+                  * @method scroll_to_cell
+                  * @param {Number} cell_number An index of the cell to view
+                  * @param {Number} time Animation time in milliseconds
+                  * @return {Number} Pixel offset from the top of the container
+                  */
                  Notebook.prototype.scroll_to_cell = function (cell_number, time) {
                      var cells = this.get_cells();
                      var time = time || 0;
                      return scroll_value;
                  };
+                 /**
+                  * Scroll to the bottom of the page.
+                  *
+                  * @method scroll_to_bottom
+                  */
                  Notebook.prototype.scroll_to_bottom = function () {
                      this.element.animate({scrollTop:this.element.get(0).scrollHeight}, 0);
                  };
+                 /**
+                  * Scroll to the top of the page.
+                  *
+                  * @method scroll_to_top
+                  */
                  Notebook.prototype.scroll_to_top = function () {
                      this.element.animate({scrollTop:0}, 0);
                  };
                  // Cell indexing, retrieval, etc.
+                 /**
+                  * Get all cell elements in the notebook.
+                  *
+                  * @method get_cell_elements
+                  * @return {jQuery} A selector of all cell elements
+                  */
                  Notebook.prototype.get_cell_elements = function () {
                      return this.element.children("div.cell");
                  };
+                 /**
+                  * Get a particular cell element.
+                  *
+                  * @method get_cell_element
+                  * @param {Number} index An index of a cell to select
+                  * @return {jQuery} A selector of the given cell.
+                  */
                  Notebook.prototype.get_cell_element = function (index) {
                      var result = null;
                      var e = this.get_cell_elements().eq(index);
                      return result;
                  };
-                 Notebook.prototype.ncells = function (cell) {
+                 /**
+                  * Count the cells in this notebook.
+                  *
+                  * @method ncells
+                  * @return {Number} The number of cells in this notebook
+                  */
+                 Notebook.prototype.ncells = function () {
                      return this.get_cell_elements().length;
                  };
+                 /**
+                  * Get all Cell objects in this notebook.
+                  *
+                  * @method get_cells
+                  * @return {Array} This notebook's Cell objects
+                  */
                  // TODO: we are often calling cells as cells()[i], which we should optimize
                  // to cells(i) or a new method.
                  Notebook.prototype.get_cells = function () {
                      });
                  };
+                 /**
+                  * Get a Cell object from this notebook.
+                  *
+                  * @method get_cell
+                  * @param {Number} index An index of a cell to retrieve
+                  * @return {Cell} A particular cell
+                  */
                  Notebook.prototype.get_cell = function (index) {
                      var result = null;
                      var ce = this.get_cell_element(index);
                      return result;
                  }
+                 /**
+                  * Get the cell below a given cell.
+                  *
+                  * @method get_next_cell
+                  * @param {Cell} cell The provided cell
+                  * @return {Cell} The next cell
+                  */
                  Notebook.prototype.get_next_cell = function (cell) {
                      var result = null;
                      var index = this.find_cell_index(cell);
                      return result;
                  }
+                 /**
+                  * Get the cell above a given cell.
+                  *
+                  * @method get_prev_cell
+                  * @param {Cell} cell The provided cell
+                  * @return {Cell} The previous cell
+                  */
                  Notebook.prototype.get_prev_cell = function (cell) {
+                     // TODO: off-by-one
+                     // nb.get_prev_cell(nb.get_cell(1)) is null
                      var result = null;
                      var index = this.find_cell_index(cell);
                      if (index !== null && index > 1) {
                      }
                      return result;
                  }
+                 /**
+                  * Get the numeric index of a given cell.
+                  *
+                  * @method find_cell_index
+                  * @param {Cell} cell The provided cell
+                  * @return {Number} The cell's numeric index
+                  */
                  Notebook.prototype.find_cell_index = function (cell) {
                      var result = null;
                      this.get_cell_elements().filter(function (index) {
                      return result;
                  };
+                 /**
+                  * Get a given index , or the selected index if none is provided.
+                  *
+                  * @method index_or_selected
+                  * @param {Number} index A cell's index
+                  * @return {Number} The given index, or selected index if none is provided.
+                  */
                  Notebook.prototype.index_or_selected = function (index) {
                      var i;
                      if (index === undefined || index === null) {
                      return i;
                  };
+                 /**
+                  * Get the currently selected cell.
+                  * @method get_selected_cell
+                  * @return {Cell} The selected cell
+                  */
                  Notebook.prototype.get_selected_cell = function () {
                      var index = this.get_selected_index();
                      return this.get_cell(index);
                  };
+                 /**
+                  * Check whether a cell index is valid.
+                  *
+                  * @method is_valid_cell_index
+                  * @param {Number} index A cell index
+                  * @return True if the index is valid, false otherwise
+                  */
                  Notebook.prototype.is_valid_cell_index = function (index) {
                      if (index !== null && index >= 0 && index < this.ncells()) {
                          return true;
                      };
                  }
+                 /**
+                  * Get the index of the currently selected cell.
+                  * @method get_selected_index
+                  * @return {Number} The selected cell's numeric index
+                  */
                  Notebook.prototype.get_selected_index = function () {
                      var result = null;
                      this.get_cell_elements().filter(function (index) {
                  // Cell selection.
+                 /**
+                  * Programmatically select a cell.
+                  *
+                  * @method select
+                  * @param {Number} index A cell's index
+                  * @return {Notebook} This notebook
+                  */
                  Notebook.prototype.select = function (index) {
                      if (this.is_valid_cell_index(index)) {
                          var sindex = this.get_selected_index()
                      return this;
                  };
+                 /**
+                  * Programmatically select the next cell.
+                  *
+                  * @method select_next
+                  * @return {Notebook} This notebook
+                  */
                  Notebook.prototype.select_next = function () {
                      var index = this.get_selected_index();
                      this.select(index+1);
                      return this;
                  };
+                 /**
+                  * Programmatically select the previous cell.
+                  *
+                  * @method select_prev
+                  * @return {Notebook} This notebook
+                  */
                  Notebook.prototype.select_prev = function () {
                      var index = this.get_selected_index();
                      this.select(index-1);
                  // Cell movement
                  /**
-                  * Move given (or selected) cell up and select it
+                  * Move given (or selected) cell up and select it.
+                  *
                   * @method move_cell_up
                   * @param [index] {integer} cell index
+                  * @return {Notebook} This notebook
                   **/
                  Notebook.prototype.move_cell_up = function (index) {
                      var i = this.index_or_selected(index);
                  /**
                   * Move given (or selected) cell down and select it
+                  *
                   * @method move_cell_down
                   * @param [index] {integer} cell index
+                  * @return {Notebook} This notebook
                   **/
                  Notebook.prototype.move_cell_down = function (index) {
                      var i = this.index_or_selected(index);
                  // Insertion, deletion.
+                 /**
+                  * Delete a cell from the notebook.
+                  *
+                  * @method delete_cell
+                  * @param [index] A cell's numeric index
+                  * @return {Notebook} This notebook
+                  */
                  Notebook.prototype.delete_cell = function (index) {
                      var i = this.index_or_selected(index);
                      var cell = this.get_selected_cell();
                      return this;
                  };
                  /**
                   * Insert a cell so that after insertion the cell is at given index.
                   *
                   *
                   * Index will be brought back into the accissible range [0,n]
                   *
+                  * @method insert_cell_at_index
                   * @param type {string} in ['code','html','markdown','heading']
                   * @param [index] {int} a valid index where to inser cell
                   *
                  /**
                   * Insert an element at given cell index.
                   *
+                  * @method _insert_element_at_index
                   * @param element {dom element} a cell element
                   * @param [index] {int} a valid index where to inser cell
                   * @private
                   *
                   * default index value is the one of currently selected cell
                   *
+                  * @method insert_cell_above
                   * @param type {string} cell type
                   * @param [index] {integer}
                   *
                   * Insert cell at end of notebook
                   *
                   * @method insert_cell_at_bottom
-                  * @param type {String} cell type
+                  * @param {String} type cell type
                   *
                   * @return the added cell; or null
                   **/
                      return this.insert_cell_below(type,len-1);
                  };
+                 /**
+                  * Turn a cell into a code cell.
+                  *
+                  * @method to_code
+                  * @param {Number} [index] A cell's index
+                  */
                  Notebook.prototype.to_code = function (index) {
                      var i = this.index_or_selected(index);
                      if (this.is_valid_cell_index(i)) {
                      };
                  };
+                 /**
+                  * Turn a cell into a Markdown cell.
+                  *
+                  * @method to_markdown
+                  * @param {Number} [index] A cell's index
+                  */
                  Notebook.prototype.to_markdown = function (index) {
                      var i = this.index_or_selected(index);
                      if (this.is_valid_cell_index(i)) {
                      };
                  };
+                 /**
+                  * Turn a cell into an HTML cell.
+                  *
+                  * @method to_html
+                  * @param {Number} [index] A cell's index
+                  */
                  Notebook.prototype.to_html = function (index) {
+                     // TODO: remove? This is never called
                      var i = this.index_or_selected(index);
                      if (this.is_valid_cell_index(i)) {
                          var source_element = this.get_cell_element(i);
                      };
                  };
+                 /**
+                  * Turn a cell into a raw text cell.
+                  *
+                  * @method to_raw
+                  * @param {Number} [index] A cell's index
+                  */
                  Notebook.prototype.to_raw = function (index) {
                      var i = this.index_or_selected(index);
                      if (this.is_valid_cell_index(i)) {
                      };
                  };
+                 /**
+                  * Turn a cell into a heading cell.
+                  *
+                  * @method to_heading
+                  * @param {Number} [index] A cell's index
+                  * @param {Number} [level] A heading level (e.g., 1 becomes &lt;h1&gt;)
+                  */
                  Notebook.prototype.to_heading = function (index, level) {
                      level = level || 1;
                      var i = this.index_or_selected(index);
                  // Cut/Copy/Paste
+                 /**
+                  * Enable UI elements for pasting cells.
+                  *
+                  * @method enable_paste
+                  */
                  Notebook.prototype.enable_paste = function () {
                      var that = this;
                      if (!this.paste_enabled) {
                      };
                  };
+                 /**
+                  * Disable UI elements for pasting cells.
+                  *
+                  * @method disable_paste
+                  */
                  Notebook.prototype.disable_paste = function () {
                      if (this.paste_enabled) {
                          $('#paste_cell_replace').addClass('ui-state-disabled').off('click');
                      };
                  };
+                 /**
+                  * Cut a cell.
+                  *
+                  * @method cut_cell
+                  */
                  Notebook.prototype.cut_cell = function () {
                      this.copy_cell();
                      this.delete_cell();
                  }
+                 /**
+                  * Copy a cell.
+                  *
+                  * @method copy_cell
+                  */
                  Notebook.prototype.copy_cell = function () {
                      var cell = this.get_selected_cell();
                      this.clipboard = cell.toJSON();
                      this.enable_paste();
                  };
+                 /**
+                  * Replace the selected cell with a cell in the clipboard.
+                  *
+                  * @method paste_cell_replace
+                  */
                  Notebook.prototype.paste_cell_replace = function () {
                      if (this.clipboard !== null && this.paste_enabled) {
                          var cell_data = this.clipboard;
                      };
                  };
+                 /**
+                  * Paste a cell from the clipboard above the selected cell.
+                  *
+                  * @method paste_cell_above
+                  */
                  Notebook.prototype.paste_cell_above = function () {
                      if (this.clipboard !== null && this.paste_enabled) {
                          var cell_data = this.clipboard;
                      };
                  };
+                 /**
+                  * Paste a cell from the clipboard below the selected cell.
+                  *
+                  * @method paste_cell_below
+                  */
                  Notebook.prototype.paste_cell_below = function () {
                      if (this.clipboard !== null && this.paste_enabled) {
                          var cell_data = this.clipboard;
                  // Cell undelete
+                 /**
+                  * Restore the most recently deleted cell.
+                  *
+                  * @method undelete
+                  */
                  Notebook.prototype.undelete = function() {
                      if (this.undelete_backup !== null && this.undelete_index !== null) {
                          var current_index = this.get_selected_index();
                  // Split/merge
+                 /**
+                  * Split the selected cell into two, at the cursor.
+                  *
+                  * @method split_cell
+                  */
                  Notebook.prototype.split_cell = function () {
                      // Todo: implement spliting for other cell types.
                      var cell = this.get_selected_cell();
                      };
                  };
+                 /**
+                  * Combine the selected cell into the cell above it.
+                  *
+                  * @method merge_cell_above
+                  */
                  Notebook.prototype.merge_cell_above = function () {
                      var index = this.get_selected_index();
                      var cell = this.get_cell(index);
                      };
                  };
+                 /**
+                  * Combine the selected cell into the cell below it.
+                  *
+                  * @method merge_cell_below
+                  */
                  Notebook.prototype.merge_cell_below = function () {
                      var index = this.get_selected_index();
                      var cell = this.get_cell(index);
                  // Cell collapsing and output clearing
+                 /**
+                  * Hide a cell's output.
+                  *
+                  * @method collapse
+                  * @param {Number} index A cell's numeric index
+                  */
                  Notebook.prototype.collapse = function (index) {
                      var i = this.index_or_selected(index);
                      this.get_cell(i).collapse();
                      this.dirty = true;
                  };
+                 /**
+                  * Show a cell's output.
+                  *
+                  * @method expand
+                  * @param {Number} index A cell's numeric index
+                  */
                  Notebook.prototype.expand = function (index) {
                      var i = this.index_or_selected(index);
                      this.get_cell(i).expand();
                      this.dirty = true;
                  };
+                 /** Toggle whether a cell's output is collapsed or expanded.
+                  *
+                  * @method toggle_output
+                  * @param {Number} index A cell's numeric index
+                  */
                  Notebook.prototype.toggle_output = function (index) {
                      var i = this.index_or_selected(index);
                      this.get_cell(i).toggle_output();
                      this.dirty = true;
                  };
+                 /**
+                  * Toggle a scrollbar for long cell outputs.
+                  *
+                  * @method toggle_output_scroll
+                  * @param {Number} index A cell's numeric index
+                  */
                  Notebook.prototype.toggle_output_scroll = function (index) {
                      var i = this.index_or_selected(index);
                      this.get_cell(i).toggle_output_scroll();
                  };
+                 /**
+                  * Hide each code cell's output area.
+                  *
+                  * @method collapse_all_output
+                  */
                  Notebook.prototype.collapse_all_output = function () {
                      var ncells = this.ncells();
                      var cells = this.get_cells();
                      this.dirty = true;
                  };
+                 /**
+                  * Expand each code cell's output area, and add a scrollbar for long output.
+                  *
+                  * @method scroll_all_output
+                  */
                  Notebook.prototype.scroll_all_output = function () {
                      var ncells = this.ncells();
                      var cells = this.get_cells();
                      this.dirty = true;
                  };
+                 /**
+                  * Expand each code cell's output area, and remove scrollbars.
+                  *
+                  * @method expand_all_output
+                  */
                  Notebook.prototype.expand_all_output = function () {
                      var ncells = this.ncells();
                      var cells = this.get_cells();
                      this.dirty = true;
                  };
+                 /**
+                  * Clear each code cell's output area.
+                  *
+                  * @method clear_all_output
+                  */
                  Notebook.prototype.clear_all_output = function () {
                      var ncells = this.ncells();
                      var cells = this.get_cells();
                  // Other cell functions: line numbers, ...
+                 /**
+                  * Toggle line numbers in the selected cell's input area.
+                  *
+                  * @method cell_toggle_line_numbers
+                  */
                  Notebook.prototype.cell_toggle_line_numbers = function() {
                      this.get_selected_cell().toggle_line_numbers();
                  };
                  // Kernel related things
+                 /**
+                  * Start a new kernel and set it on each code cell.
+                  *
+                  * @method start_kernel
+                  */
                  Notebook.prototype.start_kernel = function () {
                      var base_url = $('body').data('baseKernelUrl') + "kernels";
                      this.kernel = new IPython.Kernel(base_url);
                      };
                  };
+                 /**
+                  * Prompt the user to restart the IPython kernel.
+                  *
+                  * @method restart_kernel
+                  */
                  Notebook.prototype.restart_kernel = function () {
                      var that = this;
                      var dialog = $('<div/>');
                      });
                  };
+                 /**
+                  * Run the selected cell.
+                  *
+                  * This executes code cells, and skips all others.
+                  *
+                  * @method execute_selected_cell
+                  * @param {Object} options Customize post-execution behavior
+                  */
                  Notebook.prototype.execute_selected_cell = function (options) {
                      // add_new: should a new cell be added if we are at the end of the nb
                      // terminal: execute in terminal mode, which stays in the current cell
                      this.dirty = true;
                  };
+                 /**
+                  * Execute all cells below the selected cell.
+                  *
+                  * @method execute_cells_below
+                  */
                  Notebook.prototype.execute_cells_below = function () {
                      this.execute_cell_range(this.get_selected_index(), this.ncells());
                      this.scroll_to_bottom();
                  };
+                 /**
+                  * Execute all cells above the selected cell.
+                  *
+                  * @method execute_cells_above
+                  */
                  Notebook.prototype.execute_cells_above = function () {
                      this.execute_cell_range(0, this.get_selected_index());
                  };
+                 /**
+                  * Execute all cells.
+                  *
+                  * @method execute_all_cells
+                  */
                  Notebook.prototype.execute_all_cells = function () {
                      this.execute_cell_range(0, this.ncells());
                      this.scroll_to_bottom();
                  };
+                 /**
+                  * Execute a contiguous range of cells.
+                  *
+                  * @method execute_cell_range
+                  * @param {Number} start Index of the first cell to execute (inclusive)
+                  * @param {Number} end Index of the last cell to execute (exclusive)
+                  */
                  Notebook.prototype.execute_cell_range = function (start, end) {
                      for (var i=start; i<end; i++) {
                          this.select(i);
                  // Persistance and loading
+                 /**
+                  * Getter method for this notebook's ID.
+                  *
+                  * @method get_notebook_id
+                  * @return {String} This notebook's ID
+                  */
                  Notebook.prototype.get_notebook_id = function () {
                      return this.notebook_id;
                  };
+                 /**
+                  * Getter method for this notebook's name.
+                  *
+                  * @method get_notebook_name
+                  * @return {String} This notebook's name
+                  */
                  Notebook.prototype.get_notebook_name = function () {
                      return this.notebook_name;
                  };
+                 /**
+                  * Setter method for this notebook's name.
+                  *
+                  * @method set_notebook_name
+                  * @param {String} name A new name for this notebook
+                  */
                  Notebook.prototype.set_notebook_name = function (name) {
                      this.notebook_name = name;
                  };
+                 /**
+                  * Check that a notebook's name is valid.
+                  *
+                  * @method test_notebook_name
+                  * @param {String} nbname A name for this notebook
+                  * @return {Boolean} True if the name is valid, false if invalid
+                  */
                  Notebook.prototype.test_notebook_name = function (nbname) {
                      nbname = nbname || '';
                      if (this.notebook_name_blacklist_re.test(nbname) == false && nbname.length>0) {
                      };
                  };
+                 /**
+                  * Load a notebook from JSON (.ipynb).
+                  *
+                  * This currently handles one worksheet: others are deleted.
+                  *
+                  * @method fromJSON
+                  * @param {Object} data JSON representation of a notebook
+                  */
                  Notebook.prototype.fromJSON = function (data) {
                      var ncells = this.ncells();
                      var i;
                      }
                  };
+                 /**
+                  * Dump this notebook into a JSON-friendly object.
+                  *
+                  * @method toJSON
+                  * @return {Object} A JSON-friendly representation of this notebook.
+                  */
                  Notebook.prototype.toJSON = function () {
                      var cells = this.get_cells();
                      var ncells = cells.length;
                      return data;
                  };
+                 /**
+                  * Save this notebook on the server.
+                  *
+                  * @method save_notebook
+                  */
                  Notebook.prototype.save_notebook = function () {
                      // We may want to move the name/id/nbformat logic inside toJSON?
                      var data = this.toJSON();
                      $.ajax(url, settings);
                  };
+                 /**
+                  * Success callback for saving a notebook.
+                  *
+                  * @method save_notebook_success
+                  * @param {Object} data JSON representation of a notebook
+                  * @param {String} status Description of response status
+                  * @param {jqXHR} xhr jQuery Ajax object
+                  */
                  Notebook.prototype.save_notebook_success = function (data, status, xhr) {
                      this.dirty = false;
                      $([IPython.events]).trigger('notebook_saved.Notebook');
                  };
+                 /**
+                  * Failure callback for saving a notebook.
+                  *
+                  * @method save_notebook_error
+                  * @param {jqXHR} xhr jQuery Ajax object
+                  * @param {String} status Description of response status
+                  * @param {String} error_msg HTTP error message
+                  */
                  Notebook.prototype.save_notebook_error = function (xhr, status, error_msg) {
                      $([IPython.events]).trigger('notebook_save_failed.Notebook');
                  };
+                 /**
+                  * Request a notebook's data from the server.
+                  *
+                  * @method load_notebook
+                  * @param {String} notebook_id A notebook to load
+                  */
                  Notebook.prototype.load_notebook = function (notebook_id) {
                      var that = this;
                      this.notebook_id = notebook_id;
                      $.ajax(url, settings);
                  };
+                 /**
+                  * Success callback for loading a notebook from the server.
+                  *
+                  * Load notebook data from the JSON response.
+                  *
+                  * @method load_notebook_success
+                  * @param {Object} data JSON representation of a notebook
+                  * @param {String} status Description of response status
+                  * @param {jqXHR} xhr jQuery Ajax object
+                  */
                  Notebook.prototype.load_notebook_success = function (data, status, xhr) {
                      this.fromJSON(data);
                      if (this.ncells() === 0) {
                      $([IPython.events]).trigger('notebook_loaded.Notebook');
                  };
+                 /**
+                  * Failure callback for loading a notebook from the server.
+                  *
+                  * @method load_notebook_error
+                  * @param {jqXHR} xhr jQuery Ajax object
+                  * @param {String} textStatus Description of response status
+                  * @param {String} errorThrow HTTP error message
+                  */
                  Notebook.prototype.load_notebook_error = function (xhr, textStatus, errorThrow) {
                      if (xhr.status === 500) {
                          var msg = "An error occurred while loading this notebook. Most likely " +

General Comments 0

Write
Preview

You need to be logged in to leave comments. Login now

No TODOs yet

	Site-wide shortcuts
/	Use quick search box
g h	Goto home page
g g	Goto my private gists page
g G	Goto my public gists page
g 0-9	Goto bookmarked items from 0-9
n r	New repository page
n g	New gist page

	Repositories
g s	Goto summary page
g c	Goto changelog page
g f	Goto files page
g F	Goto files page with file search activated
g p	Goto pull requests page
g o	Goto repository settings
g O	Goto repository access permissions settings
t s	Toggle sidebar on some pages