From aa3159c2af8fc0d51d0b1acb64911e570c33fa50 Mon Sep 17 00:00:00 2001 From: dickmao Date: Wed, 5 Feb 2020 04:37:07 -0500 Subject: [PATCH] modify readme --- .appveyor.yml | 2 +- Cask | 2 +- Makefile | 3 +- README.in.rst | 40 +++--- README.rst | 40 +++--- features/notebooklist.feature | 6 +- features/step-definitions/ein-steps.el | 8 +- lisp/ein-classes.el | 4 - lisp/ein-helm.el | 173 ------------------------- lisp/ein-notebook.el | 13 +- lisp/ein-pager.el | 98 -------------- lisp/ein-pseudo-console.el | 47 ------- lisp/ein-worksheet.el | 2 +- test/test-ein-modes.el | 1 - 14 files changed, 57 insertions(+), 382 deletions(-) delete mode 100644 lisp/ein-helm.el delete mode 100644 lisp/ein-pager.el delete mode 100644 lisp/ein-pseudo-console.el diff --git a/.appveyor.yml b/.appveyor.yml index 23d109d..910799f 100644 --- a/.appveyor.yml +++ b/.appveyor.yml @@ -17,7 +17,7 @@ skip_commits: max_jobs: 1 # Build worker image (VM template) -image: Visual Studio 2015 +image: Visual Studio 2017 # scripts that are called at very beginning, before repo cloning init: diff --git a/Cask b/Cask index 5bab883..c8e8bf2 100644 --- a/Cask +++ b/Cask @@ -2,7 +2,7 @@ (source melpa) (package-descriptor "lisp/ein-pkg.el") -(files "lisp/*.el" "lisp/*.py") +(files "lisp/*.el") (development (depends-on "anaphora") diff --git a/Makefile b/Makefile index 55a699b..e7537a6 100644 --- a/Makefile +++ b/Makefile @@ -1,5 +1,6 @@ export EMACS ?= $(shell which emacs) export CASK := $(shell which cask) +TEST_VERSION := $(shell yq .jobs.build.strategy.matrix.emacs_version .github/workflows/test.yml | jq .[] | sort -n | head -1) ifeq ($(CASK),) $(error Please install CASK at https://cask.readthedocs.io/en/latest/guide/installation.html) endif @@ -28,7 +29,7 @@ README.rst: README.in.rst lisp/ein-notebook.el (describe-minor-mode \"ein:notebook-mode\") \ (with-current-buffer \"*Help*\" (princ (buffer-string))))" 2>/dev/null \ | tools/readme-sed.sh "KEYS NOTEBOOK" README.in.rst "key.*binding" > README.rst0 - sed "/CI VERSION/c"`yq .jobs.build.strategy.matrix.emacs_version .github/workflows/test.yml | jq .[] | sort -n | head -1` README.rst0 > README.rst1 + perl -ne "s/^(\s*)\S+.*CI VERSION.*$$/\$${1}$(TEST_VERSION)/; print" README.rst0 > README.rst1 grep ';;' lisp/ein.el \ | awk '/;;;\s*Commentary/{within=1;next}/;;;\s*/{within=0}within' \ | sed -e 's/^\s*;;*\s*//g' \ diff --git a/README.in.rst b/README.in.rst index ed08be5..b23814c 100644 --- a/README.in.rst +++ b/README.in.rst @@ -39,7 +39,7 @@ Alternatively, directly clone this repo and ``make install``. Usage ===== -Start EIN using **one** of the following: +Start EIN using **ONE** of the following: - Open an ``.ipynb`` file normally in emacs and press ``C-c C-o``, or, - ``M-x ein:run`` launches a jupyter process from emacs, or, @@ -52,25 +52,34 @@ Alternatively, ob-ein_. .. _Cask: https://cask.readthedocs.io/en/latest/guide/installation.html .. _Getting started: http://melpa.org/#/getting-started -Reporting bugs --------------- -EIN is tested on GNU Emacs versions -.. CI VERSION (see Makefile) -and later. +FAQ +=== -**Please file issues using** ``M-x ein:dev-bug-report-template``. +How do I... +----------- -First try ``emacs -Q -f package-initialize`` and reproduce the bug. The ``-Q`` skips any user configuration that might interfere with EIN. +... report a bug? + File an issue using ``M-x ein:dev-bug-report-template``. -Invoking ``M-x ein:dev-start-debug`` activates verbose logging. + First try ``emacs -Q -f package-initialize`` and reproduce the bug. The ``-Q`` skips any user configuration that might interfere with EIN. -EIN log buffer ``*ein:log-all*``. + Note EIN is tested only for *released* GNU Emacs versions + .. CI VERSION (see Makefile) + and later. Pre-release versions are unlikely to work. -Server log buffer (if running jupyter locally) ``*ein server*``. +... display images inline? + We find inserting images into emacs disruptive, and so default to spawning an external viewer. To override this, -HTTP requests ``M-x ein:log-pop-to-request-buffer``. + :: -Kernel messaging (must be run from notebook buffer) ``M-x ein:dev-pop-to-debug-channels``. + M-x customize-group RET ein + Ein:Output Area Inlined Images + +... configure the external image viewer? + :: + + M-x customize-group RET mailcap + Mailcap User Mime Data .. _spacemacs layer: https://github.com/syl20bnr/spacemacs/tree/master/layers/%2Blang/ipython-notebook .. _company-mode: https://github.com/company-mode/company-mode @@ -116,8 +125,3 @@ Keymap (C-h m) :: .. KEYS NOTEBOOK (see Makefile) - -License -======= -Emacs IPython Notebook is licensed under GPL v3. -See COPYING for details. diff --git a/README.rst b/README.rst index 84be71d..f02995c 100644 --- a/README.rst +++ b/README.rst @@ -48,7 +48,7 @@ Alternatively, directly clone this repo and ``make install``. Usage ===== -Start EIN using **one** of the following: +Start EIN using **ONE** of the following: - Open an ``.ipynb`` file normally in emacs and press ``C-c C-o``, or, - ``M-x ein:run`` launches a jupyter process from emacs, or, @@ -61,25 +61,34 @@ Alternatively, ob-ein_. .. _Cask: https://cask.readthedocs.io/en/latest/guide/installation.html .. _Getting started: http://melpa.org/#/getting-started -Reporting bugs --------------- -EIN is tested on GNU Emacs versions -25.1 -and later. +FAQ +=== -**Please file issues using** ``M-x ein:dev-bug-report-template``. +How do I... +----------- -First try ``emacs -Q -f package-initialize`` and reproduce the bug. The ``-Q`` skips any user configuration that might interfere with EIN. +... report a bug? + File an issue using ``M-x ein:dev-bug-report-template``. -Invoking ``M-x ein:dev-start-debug`` activates verbose logging. + First try ``emacs -Q -f package-initialize`` and reproduce the bug. The ``-Q`` skips any user configuration that might interfere with EIN. -EIN log buffer ``*ein:log-all*``. + Note EIN is tested only for *released* GNU Emacs versions + 25.1 + and later. Pre-release versions are unlikely to work. -Server log buffer (if running jupyter locally) ``*ein server*``. +... display images inline? + We find inserting images into emacs disruptive, and so default to spawning an external viewer. To override this, -HTTP requests ``M-x ein:log-pop-to-request-buffer``. + :: -Kernel messaging (must be run from notebook buffer) ``M-x ein:dev-pop-to-debug-channels``. + M-x customize-group RET ein + Ein:Output Area Inlined Images + +... configure the external image viewer? + :: + + M-x customize-group RET mailcap + Mailcap User Mime Data .. _spacemacs layer: https://github.com/syl20bnr/spacemacs/tree/master/layers/%2Blang/ipython-notebook .. _company-mode: https://github.com/company-mode/company-mode @@ -195,8 +204,3 @@ Keymap (C-h m) C-c M-w ein:worksheet-copy-cell-km C-c M-{ ein:notebook-worksheet-move-prev-km C-c M-} ein:notebook-worksheet-move-next-km - -License -======= -Emacs IPython Notebook is licensed under GPL v3. -See COPYING for details. diff --git a/features/notebooklist.feature b/features/notebooklist.feature index 71027a5..089c001 100644 --- a/features/notebooklist.feature +++ b/features/notebooklist.feature @@ -28,6 +28,7 @@ Scenario: Resync @stop Scenario: Stop after closing notebook Given I am in notebooklist buffer + Given I clear log expr "ein:log-all-buffer-name" And I click on "New Notebook" And no notebooks pending And I switch to buffer like "Untitled" @@ -37,6 +38,7 @@ Scenario: Stop after closing notebook And I keep clicking "Resync" until "Stop" And I click on "Stop" And I switch to log expr "ein:log-all-buffer-name" + And I dump buffer Then I should see "kernel-delete-session--success" And I am in notebooklist buffer And I go to word "Untitled" @@ -48,18 +50,18 @@ Scenario: Stop after closing notebook @delete Scenario: Delete closes buffers and sessions Given I am in notebooklist buffer + Given I clear log expr "ein:log-all-buffer-name" And I click on "New Notebook" And no notebooks pending And I switch to buffer like "Untitled" And I am in notebooklist buffer And I clear log expr "ein:log-all-buffer-name" And I click on "Delete" - And I wait for buffer to not say "Untitled" + And I wait for buffer to not say "Stop" And I dump buffer Then eval "(should-not (ein:notebook-opened-notebooks)))" Then eval "(should-not (seq-some (lambda (b) (cl-search "Untitled" (buffer-name b))) (buffer-list)))" And I switch to log expr "ein:log-all-buffer-name" - And I dump buffer Then I should see "kernel-delete-session--success" Then I should see "notebooklist-delete-notebook--complete" diff --git a/features/step-definitions/ein-steps.el b/features/step-definitions/ein-steps.el index 1a1b861..25283b8 100644 --- a/features/step-definitions/ein-steps.el +++ b/features/step-definitions/ein-steps.el @@ -120,11 +120,9 @@ (cl-loop repeat 10 until (zerop (hash-table-count *ein:notebook--pending-query*)) do (sleep-for 0 500) - finally do (should (zerop (hash-table-count *ein:notebook--pending-query*)))))) - -(When "^no notebooks open$" - (lambda () - (should ()))) + finally do (should (zerop (hash-table-count *ein:notebook--pending-query*)))) + (with-current-buffer ein:log-all-buffer-name + (And "I wait for buffer to say \"ein:query-sessions--complete\"")))) (When "^I switch to buffer like \"\\(.+\\)\"$" (lambda (substr) diff --git a/lisp/ein-classes.el b/lisp/ein-classes.el index 8b863be..199cc72 100644 --- a/lisp/ein-classes.el +++ b/lisp/ein-classes.el @@ -112,9 +112,6 @@ `ein:$notebook-kernelinfo' : `ein:kernelinfo' `ein:kernelinfo' instance. -`ein:$notebook-pager' - Variable for `ein:pager-*' functions. See ein-pager.el. - `ein:$notebook-dirty' : boolean Set to `t' if notebook has unsaved changes. Otherwise `nil'. @@ -148,7 +145,6 @@ kernel kernelinfo kernelspec - pager dirty metadata notebook-name diff --git a/lisp/ein-helm.el b/lisp/ein-helm.el deleted file mode 100644 index 65a5c63..0000000 --- a/lisp/ein-helm.el +++ /dev/null @@ -1,173 +0,0 @@ -;;; ein-helm.el --- Helm/anything commands - -;; Copyright (C) 2012 Takafumi Arakaki - -;; Author: Takafumi Arakaki - -;; This file is NOT part of GNU Emacs. - -;; ein-helm.el is free software: you can redistribute it and/or modify -;; it under the terms of the GNU General Public License as published by -;; the Free Software Foundation, either version 3 of the License, or -;; (at your option) any later version. - -;; ein-helm.el is distributed in the hope that it will be useful, -;; but WITHOUT ANY WARRANTY; without even the implied warranty of -;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -;; GNU General Public License for more details. - -;; You should have received a copy of the GNU General Public License -;; along with ein-helm.el. If not, see . - -;;; Commentary: - -;; - -;;; Code: - -(declare-function anything-other-buffer "anything") -(declare-function helm-other-buffer "helm") - -(require 'ein-kernel) - - -;;; Macros - -(defmacro ein:helm-export-source (name) - (let* ((orig-source (intern (format "ein:helm-source-%s" name))) - (any-source (intern (format "anything-c-source-ein-%s" name))) - (helm-source (intern (format "helm-c-source-ein-%s" name))) - (docstring (format "Alias to `%s'" orig-source))) - `(progn - (defvaralias ',helm-source ',orig-source ,docstring) - (defvaralias ',any-source ',orig-source ,docstring)))) - - -;;; Dynamic Variables - -(defvar ein:helm-pattern 'helm-pattern - "Dynamically bound to one of `helm-pattern' or `anything-pattern'.") - -(defvar ein:helm-kernel nil - "Dynamically bound to a kernel object.") - - - -;;; History search - -(defcustom ein:helm-kernel-history-search-auto-pattern t - "Automatically construct search pattern when non-`nil'. - -1. Single space is converted to \"*\". -2. A backslash followed by a space is converted to a single space. -3. A \"*\" is added at the beginning and end of the pattern. - -This variable applies to both `helm-ein-kernel-history' and -`anything-ein-kernel-history'." - :type 'boolean - :group 'ein) - -(defun ein:helm-kernel-history-search-construct-pattern (pattern) - (when ein:helm-kernel-history-search-auto-pattern - (setq pattern - (replace-regexp-in-string "[^\\\\ ]\\( \\)[^\\\\ ]" - "*" pattern nil nil 1)) - (setq pattern - (replace-regexp-in-string "\\\\ " " " pattern)) - (setq pattern (concat "*" pattern "*"))) - pattern) - -(defun ein:helm-kernel-history-search-get-candidates () - "Retrieve search result from kernel. -It requires the following dynamical variables: -* `ein:helm-pattern' -* `ein:helm-kernel'" - (let* ((pattern (ein:helm-kernel-history-search-construct-pattern - (eval ein:helm-pattern))) - (candidates (ein:kernel-history-search-synchronously - ein:helm-kernel pattern :unique t))) - ;; Most recent history first: - (nreverse candidates))) - -(defvar ein:helm-source-kernel-history - '((name . "IPython history") - (candidates . ein:helm-kernel-history-search-get-candidates) - (requires-pattern . 3) - ;; There is no need to filter out candidates: - (match . (identity)) - (volatile) - (action . insert) - (delayed) - (multiline)) - "Helm/anything source for searching kernel history.") - -;;;###autoload -(defun anything-ein-kernel-history () - "Search kernel execution history then insert the selected one." - (interactive) - (let ((ein:helm-pattern 'anything-pattern) - (ein:helm-kernel (ein:get-kernel-or-error))) - (anything-other-buffer ein:helm-source-kernel-history "*anything ein*"))) - -;;;###autoload -(defun helm-ein-kernel-history () - "Search kernel execution history then insert the selected one." - (interactive) - (let ((ein:helm-pattern 'helm-pattern) - (ein:helm-kernel (ein:get-kernel-or-error))) - (helm-other-buffer ein:helm-source-kernel-history "*helm ein*"))) - - - -;;; Notebook buffers - -(defvar ein:helm-source-notebook-buffers - '((name . "All IPython notebook buffers") - (candidates . ein:notebook-opened-buffer-names) - (type . buffer)) - "Helm/anything source for all opened notebook buffers.") - -(defvar ein:helm-source-modified-notebook-buffers - '((name . "Modified IPython notebook buffers") - (candidates - . (lambda () - (ein:notebook-opened-buffer-names #'ein:notebook-modified-p))) - (type . buffer)) - "Helm/anything source for modified notebook buffers.") - -(defvar ein:helm-source-saved-notebook-buffers - '((name . "Saved IPython notebook buffers") - (candidates - . (lambda () - (ein:notebook-opened-buffer-names - (lambda (nb) (not (ein:notebook-modified-p nb)))))) - (type . buffer)) - "Helm/anything source for saved notebook buffers.") - - -;;; "Export" sources to `helm/anything-c-source-*' -(ein:helm-export-source notebook-buffers) -(ein:helm-export-source modified-notebook-buffers) -(ein:helm-export-source saved-notebook-buffers) - - -;;; Helm/anything commands - -(defvar ein:helm-notebook-buffer-sources - '(ein:helm-source-modified-notebook-buffers - ein:helm-source-saved-notebook-buffers)) - -;;;###autoload -(defun anything-ein-notebook-buffers () - "Choose opened notebook using anything.el interface." - (interactive) - (anything-other-buffer ein:helm-notebook-buffer-sources "*anything ein*")) - -;;;###autoload -(defun helm-ein-notebook-buffers () - "Choose opened notebook using helm interface." - (interactive) - (helm-other-buffer ein:helm-notebook-buffer-sources "*helm ein*")) - -(provide 'ein-helm) -;;; ein-helm.el ends here diff --git a/lisp/ein-notebook.el b/lisp/ein-notebook.el index 7a4c2c8..dd8f496 100644 --- a/lisp/ein-notebook.el +++ b/lisp/ein-notebook.el @@ -49,8 +49,6 @@ (require 'ein-scratchsheet) (require 'ein-notification) (require 'ein-completer) -(require 'ein-pager) -(require 'ein-pseudo-console) (require 'ein-events) (require 'ein-notification) (require 'ein-kill-ring) @@ -133,8 +131,6 @@ Current buffer for these functions is set to the notebook buffer.") ;; is at: ;; https://github.com/ipython/ipython/wiki/IPEP-16%3A-Notebook-multi-directory-dashboard-and-URL-mapping - -(defvar ein:notebook-pager-buffer-name-template "*ein:pager %s/%s*") (defvar ein:notebook-buffer-name-template "*ein: %s/%s*") (ein:deflocal ein:%notebook% nil @@ -386,14 +382,7 @@ of minor mode." (defun ein:notebook-bind-events (notebook events) "Bind events related to PAGER to the event handler EVENTS." (setf (ein:$notebook-events notebook) events) - (ein:worksheet-class-bind-events events) - ;; Bind events for sub components: - (setf (ein:$notebook-pager notebook) - (ein:pager-new - (format ein:notebook-pager-buffer-name-template - (ein:$notebook-url-or-port notebook) - (ein:$notebook-notebook-name notebook)) - (ein:$notebook-events notebook)))) + (ein:worksheet-class-bind-events events)) (defalias 'ein:notebook-reconnect-kernel 'ein:notebook-reconnect-session-command "The distinction between kernel and session is a bit mysterious, all the action is now occurring in `ein:notebook-reconnect-session-command' these days, for which this function is now an alias.") diff --git a/lisp/ein-pager.el b/lisp/ein-pager.el deleted file mode 100644 index 5c8daab..0000000 --- a/lisp/ein-pager.el +++ /dev/null @@ -1,98 +0,0 @@ -;;; ein-pager.el --- Pager module - -;; Copyright (C) 2012- Takafumi Arakaki - -;; Author: Takafumi Arakaki - -;; This file is NOT part of GNU Emacs. - -;; ein-pager.el is free software: you can redistribute it and/or modify -;; it under the terms of the GNU General Public License as published by -;; the Free Software Foundation, either version 3 of the License, or -;; (at your option) any later version. - -;; ein-pager.el is distributed in the hope that it will be useful, -;; but WITHOUT ANY WARRANTY; without even the implied warranty of -;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -;; GNU General Public License for more details. - -;; You should have received a copy of the GNU General Public License -;; along with ein-pager.el. If not, see . - -;;; Commentary: - -;; - -;;; Code: - -(require 'ansi-color) - -(require 'ein-core) -(require 'ein-events) -(require 'view) - -;; FIXME: Make a class with `:get-notebook-name' slot like `ein:worksheet' - -(declare-function ess-help-underline "ess-help") - -(defun ein:pager-new (name events) - ;; currently pager = name. - (ein:pager-bind-events name events) - name) - -(defun ein:pager-bind-events (pager events) - "Bind events related to PAGER to the event handler EVENTS." - (ein:events-on events - 'open_with_text.Pager - #'ein:pager--open-with-text - pager)) - -(defun ein:pager--open-with-text (pager data) - (let ((text (plist-get data :text))) - (unless (equal (ein:trim text) "") - (ein:pager-clear pager) - (ein:pager-expand pager) - (ein:pager-append-text pager text)))) - -(defun ein:pager-clear (pager) - (ein:with-read-only-buffer (get-buffer-create pager) - (erase-buffer))) - -(defun ein:pager-expand (pager) - (pop-to-buffer (get-buffer-create pager)) - (goto-char (point-min))) - -(defun ein:pager-append-text (pager text) - (ein:with-read-only-buffer (get-buffer-create pager) - (insert (ansi-color-apply text)) - (if (featurep 'ess-help) - (ess-help-underline)) - (unless (eql 'ein:pager-mode major-mode) - (ein:pager-mode)))) - -;; FIXME: this should be automatically called when opening pager. -(defun ein:pager-goto-docstring-bset-loc () - "Goto the best location of the documentation." - (interactive) - (goto-char (point-min)) - (search-forward-regexp "^Docstring:") - (beginning-of-line 0) - (recenter 0)) - -(defvar ein:pager-mode-map - (let ((map (make-sparse-keymap))) - (define-key map "\C-c\C-b" 'ein:pager-goto-docstring-bset-loc) - map) - "Keymap for ein:pager-mode.") - -(define-derived-mode ein:pager-mode view-mode "ein:pager" - "IPython notebook pager mode. -Commands: -\\{ein:pager-mode-map}" - (setq-local view-no-disable-on-exit t) - (font-lock-mode)) - - -(provide 'ein-pager) - -;;; ein-pager.el ends here diff --git a/lisp/ein-pseudo-console.el b/lisp/ein-pseudo-console.el deleted file mode 100644 index 71d5d7e..0000000 --- a/lisp/ein-pseudo-console.el +++ /dev/null @@ -1,47 +0,0 @@ -;;; ein-pseudo-console.el --- Pseudo console mode - -;; Copyright (C) 2012 Takafumi Arakaki - -;; Author: Takafumi Arakaki - -;; This file is NOT part of GNU Emacs. - -;; ein-pseudo-console.el is free software: you can redistribute it -;; and/or modify it under the terms of the GNU General Public License -;; as published by the Free Software Foundation, either version 3 of -;; the License, or (at your option) any later version. - -;; ein-pseudo-console.el is distributed in the hope that it will be -;; useful, but WITHOUT ANY WARRANTY; without even the implied warranty -;; of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -;; GNU General Public License for more details. - -;; You should have received a copy of the GNU General Public License -;; along with ein-pseudo-console.el. -;; If not, see . - -;;; Commentary: - -;; - -;;; Code: - -(defvar ein:pseudo-console-mode-map (make-sparse-keymap)) - -(let ((map ein:pseudo-console-mode-map)) - (define-key map "\C-m" 'ein:worksheet-execute-cell-and-insert-below)) - -;;;###autoload -(define-minor-mode ein:pseudo-console-mode - "Pseudo console mode. Hit RET to execute code." - :lighter " ein:pseudo" - :keymap ein:pseudo-console-mode-map - :group 'ein) - -;; To avoid MuMaMo to discard `ein:pseudo-console-mode', make it -;; permanent local. -(put 'ein:pseudo-console-mode 'permanent-local t) - -(provide 'ein-pseudo-console) - -;;; ein-pseudo-console.el ends here diff --git a/lisp/ein-worksheet.el b/lisp/ein-worksheet.el index 858500e..c07269f 100644 --- a/lisp/ein-worksheet.el +++ b/lisp/ein-worksheet.el @@ -1058,7 +1058,7 @@ cell bellow." (cl-defun ein:worksheet-execute-all-cells (ws &key above below) "Execute all cells in the current worksheet buffer. -If :above or :below specified, execute above/below the current cell (exclusively)." +If :above or :below specified, execute above/below the current cell." (interactive (list (ein:worksheet--get-ws-or-error))) (let* ((all (seq-filter #'ein:codecell-p (ein:worksheet-get-cells ws))) (current-id (aif (ein:worksheet-get-current-cell) (slot-value it 'cell-id))) diff --git a/test/test-ein-modes.el b/test/test-ein-modes.el index f174e77..15c20e7 100644 --- a/test/test-ein-modes.el +++ b/test/test-ein-modes.el @@ -31,4 +31,3 @@ (eintest:test-keymap ein:notebook-mode-map) (eintest:test-keymap ein:traceback-mode-map) (eintest:test-keymap ein:shared-output-mode-map) -(eintest:test-keymap ein:pager-mode-map)