diff --git a/docs/conf.py b/docs/conf.py index 906b8f9..0c2c406 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -35,6 +35,7 @@ 'sphinx.ext.viewcode', 'sphinx.ext.napoleon', 'sphinx.ext.doctest', + 'sphinx.ext.intersphinx', ] # The master toctree document. @@ -54,6 +55,11 @@ # This pattern also affects html_static_path and html_extra_path. exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] +# Warn on broken cross references +nitpicky = True + +intersphinx_mapping = {'python': ('https://docs.python.org/3', None)} + # -- Options for HTML output ------------------------------------------------- diff --git a/docs/elisp.rst b/docs/elisp.rst index 698ad01..7dd014a 100644 --- a/docs/elisp.rst +++ b/docs/elisp.rst @@ -1,3 +1,6 @@ +.. py:currentmodule:: emacs.elisp.ast + + Representing Emacs lisp code in Python ====================================== @@ -50,8 +53,18 @@ Python lists are converted to quoted Elisp lists, while tuples are left unquoted -Elements of lists/tuples are recursively converted using :meth:`to_elisp` if -they are not already instances of :class:`ElispAstNode`. +Python dicts and other mapping types are converted using :func:`make_alist` (see +below): + +.. doctest:: + + >>> el.to_elisp({'a': 1, 'b': 2}) + + + +Elements of composite data types (lists, tuples, dicts) are recursively +converted using :meth:`to_elisp` if they are not already instances of +:class:`ElispAstNode`. You can use :func:`quote` to quote a value. It will also convert strings to quoted symbols: @@ -69,14 +82,22 @@ quoted symbols: -Other shortcuts are :func:`cons` to create a cons cell, or :func:`symbols` to -create a list of symbols: +A a form that must be constructed directly because it has no Python equivalent +is the cons cell, represented with the class :class:`Cons`: .. doctest:: - >>> el.cons(el.Symbol('a'), 1) + >>> el.Cons(el.Symbol('a'), 1) + >>> el.quote(el.Cons(el.Symbol('a'), 1)) + + + +The :func:`symbols` function can be used to create a list of symbols: + +.. doctest:: + >>> el.symbols('a', 'b', 'c') @@ -109,7 +130,10 @@ be inserted verbatim in the given location: Using Elisp forms ----------------- -Elisp forms can be passed to :meth:`Elisp.eval` and :meth:`Elisp.getresult` for +.. py:currentmodule:: emacs.emacs + + +Elisp forms can be passed to :meth:`Emacs.eval` and :meth:`Emacs.getresult` for execution. You can also convert them to strings to produce (hopefully) syntactically-correct Elisp code. @@ -117,9 +141,12 @@ syntactically-correct Elisp code. Elisp DSL --------- +.. py:currentmodule:: emacs.elisp.ast + + This package also includes an unholy abomination of a DSL that lets you write Elisp code in Python. The DSL is implemented through a singleton object which -is importable as :data:`emacs.elisp.E`:: +is importable as :data:`emacs.elisp.E `:: >>> from emacs.elisp import E @@ -163,7 +190,7 @@ Symbols can be called as functions, generating Elisp function calls: Additionally, the ``Q``, ``C``, ``S``, and ``R`` methods are aliases for the -:func:`quote`, :func:`cons`, :func:`symbols`, and :class:`Raw`, respectively. +:func:`quote`, :class:`Cons`, :func:`symbols`, and :class:`Raw`, respectively. Using just the ``E`` object, it is possible to write complex Elisp forms: diff --git a/docs/usage.rst b/docs/usage.rst index 925d66e..a331914 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -1,3 +1,6 @@ +.. py:currentmodule:: emacs.emacs + + Basic usage =========== diff --git a/emacs/elisp/ast.py b/emacs/elisp/ast.py index d02c452..1b29e93 100644 --- a/emacs/elisp/ast.py +++ b/emacs/elisp/ast.py @@ -211,7 +211,8 @@ def quote(value): Parameters ---------- - value : Elisp value to quote. + value + Elisp value to quote. Returns ------- diff --git a/emacs/elisp/dsl.py b/emacs/elisp/dsl.py index 9da2c0b..98ef044 100644 --- a/emacs/elisp/dsl.py +++ b/emacs/elisp/dsl.py @@ -7,9 +7,7 @@ class ElispSingleton: - """Singleton object which implements the Elisp DSL. - - + """Class of the singleton :data:`.E`. """ __instance = None @@ -44,4 +42,5 @@ def __call__(self, value): R = staticmethod(Raw) +#: Singleton object which implements the Elisp DSL. E = ElispSingleton() diff --git a/emacs/emacs.py b/emacs/emacs.py index d7e3af7..ee0796a 100644 --- a/emacs/emacs.py +++ b/emacs/emacs.py @@ -66,7 +66,7 @@ def from_calledprocess(cls, src, cpe): Parameters ---------- - src : str or emacs.elisp.ElispAstNode + src : str or emacs.elisp.ast.ElispAstNode Source code which was to be evaluated. cpe : subprocess.CalledProcessError @@ -273,7 +273,8 @@ def getresult(self, source, is_json=False, **kwargs): Returns ------- - Parsed value. + object + Parsed value. Raises ------