modify readme

This commit is contained in:
dickmao 2020-02-05 04:37:07 -05:00
parent 7291f61fe1
commit aa3159c2af
14 changed files with 57 additions and 382 deletions

View file

@ -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:

2
Cask
View file

@ -2,7 +2,7 @@
(source melpa)
(package-descriptor "lisp/ein-pkg.el")
(files "lisp/*.el" "lisp/*.py")
(files "lisp/*.el")
(development
(depends-on "anaphora")

View file

@ -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' \

View file

@ -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.

View file

@ -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.

View file

@ -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"

View file

@ -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)

View file

@ -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

View file

@ -1,173 +0,0 @@
;;; ein-helm.el --- Helm/anything commands
;; Copyright (C) 2012 Takafumi Arakaki
;; Author: Takafumi Arakaki <aka.tkf at gmail.com>
;; 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 <http://www.gnu.org/licenses/>.
;;; 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

View file

@ -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.")

View file

@ -1,98 +0,0 @@
;;; ein-pager.el --- Pager module
;; Copyright (C) 2012- Takafumi Arakaki
;; Author: Takafumi Arakaki <aka.tkf at gmail.com>
;; 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 <http://www.gnu.org/licenses/>.
;;; 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

View file

@ -1,47 +0,0 @@
;;; ein-pseudo-console.el --- Pseudo console mode
;; Copyright (C) 2012 Takafumi Arakaki
;; Author: Takafumi Arakaki <aka.tkf at gmail.com>
;; 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 <http://www.gnu.org/licenses/>.
;;; 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

View file

@ -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)))

View file

@ -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)