Merge pull request #2560 from Kodiologist/docs

Miscellaneous documentation changes

docs/.gitignore

@@ -1,2 +1 @@
 _build
-cheatsheet.rst

docs/api.rst

@@ -50,7 +50,7 @@ base names, such that ``hy.core.macros.foo`` can be called as just ``foo``.
       (defn #^ int add1 [#^ int x] (+ x 1))
       (fn #^ int [#^ int y] (+ y 2))
 
-   For annotating items with generic types, the :hy:func:`of <hyrule.misc.of>`
+   For annotating items with generic types, the :hy:func:`of <hyrule.of>`
    macro will likely be of use.
 
    An issue with type annotations is that, as of this writing, we know of no Python type-checker that can work with :py:mod:`ast` objects or bytecode files. They all need Python source text. So you'll have to translate your Hy with ``hy2py`` in order to actually check the types.
@@ -249,7 +249,7 @@ base names, such that ``hy.core.macros.foo`` can be called as just ``foo``.
    In a loop with multiple iteration clauses, such as ``(for [x xs y ys] …)``,
    ``break`` only breaks out of the innermost iteration, not the whole form. To
    jump out of the whole form, enclose it in a :hy:func:`block
-   <hyrule.control.block>` and use ``block-ret`` instead of ``break``. In
+   <hyrule.block>` and use ``block-ret`` instead of ``break``. In
    the case of :hy:func:`for`, but not :hy:func:`lfor` and the other
    comprehension forms, you may also enclose it in a function and use
    :hy:func:`return`.
@@ -303,9 +303,9 @@ base names, such that ``hy.core.macros.foo`` can be called as just ``foo``.
    In a loop with multiple iteration clauses, such as ``(for [x xs y ys] …)``,
    ``continue`` applies to the innermost iteration, not the whole form. To jump
    to the next step of an outer iteration, try rewriting your loop as multiple
-   nested loops and interposing a :hy:func:`block <hyrule.control.block>`, as
-   in ``(for [x xs] (block (for [y ys] …)))``. You can then use ``block-ret``
-   in place of ``continue``.
+   nested loops and interposing a :hy:func:`block <hyrule.block>`, as in
+   ``(for [x xs] (block (for [y ys] …)))``. You can then use ``block-ret`` in
+   place of ``continue``.
 
 .. hy:macro:: (do [#* body])
 
@@ -744,8 +744,8 @@ base names, such that ``hy.core.macros.foo`` can be called as just ``foo``.
    <https://en.wikipedia.org/wiki/Switch_statement>`_ construct, and
    retains all of Python's limitations on match patterns. For example, you
    can't match against the value of a variable. For more flexible branching
-   constructs, see Hyrule's :hy:func:`branch <hyrule.control.branch>` and
-   :hy:func:`case <hyrule.control.case>`, or simply use :hy:func:`cond
+   constructs, see Hyrule's :hy:func:`branch <hyrule.branch>` and
+   :hy:func:`case <hyrule.case>`, or simply use :hy:func:`cond
    <hy.core.macros.cond>`.
 
 .. hy:macro:: (defclass [arg1 #* args])
@@ -1350,6 +1350,10 @@ the following methods
 
 .. hy:autoclass:: hy.I
 
+.. hy:class:: (hy.R)
+
+   There is no actual object named ``hy.R``. Rather, this syntax is :ref:`recognized specially by the compiler <hy.R>` as a shorthand for requiring and calling a macro.
+
 Reader Macros
 -------------
 

docs/conf.py

@@ -75,74 +75,6 @@
 import hy
 hy.I = type(hy.I)  # A trick to enable `hy:autoclass:: hy.I`
 
-# ** Generate Cheatsheet
-import json
-from itertools import zip_longest
-from pathlib import Path
-
-
-def refize(spec):
-    role = ":hy:func:"
-    if isinstance(spec, dict):
-        _name = spec["name"]
-        uri = spec["uri"]
-        if spec.get("internal"):
-            role = ":ref:"
-    else:
-        uri = spec
-        _name = str.split(uri, ".")[-1]
-    return "{}`{} <{}>`".format(role, _name, uri)
-
-
-def format_refs(refs, indent):
-    args = [iter(map(refize, refs))]
-    ref_groups = zip_longest(*args, fillvalue="")
-    return str.join(
-        " \\\n" + " " * (indent + 3),
-        [str.join(" ", ref_group) for ref_group in ref_groups],
-    )
-
-
-def format_row(category, divider_loc):
-    return "{title: <{width}} | {methods}".format(
-        width=divider_loc,
-        title=category["name"],
-        methods=format_refs(category["methods"], divider_loc),
-    )
-
-
-def format_table(table_spec):
-    table_name = table_spec["name"]
-    categories = table_spec["categories"]
-    longest_cat_name = max(len(category["name"]) for category in categories)
-    table = [
-        table_name,
-        "-" * len(table_name),
-        "",
-        "=" * longest_cat_name + " " + "=" * 25,
-        *(format_row(category, longest_cat_name) for category in categories),
-        "=" * longest_cat_name + " " + "=" * 25,
-        "",
-    ]
-    return "\n".join(table)
-
-
-# Modifications to the cheatsheet should be added in `cheatsheet.json`
-cheatsheet_spec = json.loads(Path("./docs/cheatsheet.json").read_text())
-cheatsheet = [
-    "..",
-    "    DO NOT MODIFY THIS FILE. IT IS AUTO GENERATED BY ``conf.py``",
-    "    If you need to change or add methods, modify ``cheatsheet_spec`` in ``conf.py``",
-    "",
-    ".. _cheatsheet:",
-    "",
-    "Cheatsheet",
-    "==========",
-    "",
-    *map(format_table, cheatsheet_spec),
-]
-Path("./docs/cheatsheet.rst").write_text("\n".join(cheatsheet))
-
 
 # ** Sphinx App Setup
 

docs/index.rst

@@ -37,6 +37,5 @@ Linux and Windows), and on recent versions of PyPy and Pyodide.
    cli
    interop
    model_patterns
-   cheatsheet
    api
    hacking

docs/macros.rst

@@ -114,7 +114,7 @@ A better approach is to use :hy:func:`hy.gensym` to choose your variable name::
         (setv ~g (.upper ~arg))
         (+ ~g ~g)))
 
-Hyrule provides some macros that make using gensyms more convenient, like :hy:func:`defmacro! <hyrule.macrotools.defmacro!>` and :hy:func:`with-gensyms <hyrule.macrotools.with-gensyms>`.
+Hyrule provides some macros that make using gensyms more convenient, like :hy:func:`defmacro! <hyrule.defmacro!>` and :hy:func:`with-gensyms <hyrule.with-gensyms>`.
 
 Macro subroutines
 ~~~~~~~~~~~~~~~~~

docs/syntax.rst

@@ -407,7 +407,7 @@ first element.
 
   .. _hy.R:
 
-  - Exception: expressions like ``((. hy R module-name macro-name) …)``, or equivalently ``(hy.R.module-name.macro-name …)``, get special treatment. They import the module ``module-name`` and call its macro ``macro-name``, so ``(hy.R.foo.bar 1)`` is equivalent to ``(require foo) (foo.bar 1)``, but without bringing ``foo`` or ``foo.bar`` into scope. Thus ``hy.R`` is convenient syntactic sugar for macros you'll only call once in a file, or for macros that you want to appear in the expansion of other macros without having to call :hy:func:`require` in the expansion. As with :hy:class:`hy.I`, dots in the module name must be replaced with slashes.
+  - Exception: expressions like ``((. hy R module-name macro-name) …)``, or equivalently ``(hy.R.module-name.macro-name …)``, get special treatment. They :hy:func:`require` the module ``module-name`` and call its macro ``macro-name``, so ``(hy.R.foo.bar 1)`` is equivalent to ``(require foo) (foo.bar 1)``, but without bringing ``foo`` or ``foo.bar`` into scope. Thus ``hy.R`` is convenient syntactic sugar for macros you'll only call once in a file, or for macros that you want to appear in the expansion of other macros without having to call :hy:func:`require` in the expansion. As with :hy:class:`hy.I`, dots in the module name must be replaced with slashes.
 
 - Otherwise, the expression is compiled into a Python-level call, with the
   first element being the calling object. (So, you can call a function that has

docs/tutorial.rst

@@ -312,7 +312,7 @@ arbitrary Hy forms to be executed as code. There are several helper macros that
 make it easy to construct forms programmatically, such as :hy:func:`quote`
 (``'``), :hy:func:`quasiquote` (`````), :hy:func:`unquote` (``~``),
 :hy:func:`unquote-splice` (``~@``), and :hy:func:`defmacro!
-<hyrule.macrotools.defmacro!>`. The previous chapter has :ref:`a simple example
+<hyrule.defmacro!>`. The previous chapter has :ref:`a simple example
 <do-while>` of using ````` and ``~@`` to define a new control construct
 ``do-while``.
 

hy/core/macros.hy

@@ -41,7 +41,7 @@
 
 
 (defmacro when [test #* body]
-  #[[Shorthand for ``(if test (do …) None)``. See :hy:func:`if`. For a logically negated version, see Hyrule's :hy:func:`unless <hyrule.control.unless>`.
+  #[[Shorthand for ``(if test (do …) None)``. See :hy:func:`if`. For a logically negated version, see Hyrule's :hy:func:`unless <hyrule.unless>`.
   ::
 
       (when panic

hy/core/util.hy

@@ -104,7 +104,7 @@
       (print (hy.repr (hy.macroexpand '(m 5))))
         ; => '0
 
-  Note that in general, macro calls in the arguments of the expression still won't expanded. To expand these, too, try Hyrule's :hy:func:`macroexpand-all <hyrule.macrotools.macroexpand-all>`."
+  Note that in general, macro calls in the arguments of the expression still won't expanded. To expand these, too, try Hyrule's :hy:func:`macroexpand-all <hyrule.macroexpand-all>`."
   (_macroexpand model (or module (calling-module)) macros))
 
 (defn macroexpand-1 [model [module None] [macros None]]

hy/models.py

@@ -381,8 +381,8 @@ class Sequence(Object, tuple):
 
     When you're recursively descending through a tree of models, testing a model with
     ``(isinstance x hy.models.Sequence)`` is useful for deciding whether to iterate over
-    ``x``. You can also use the Hyrule function :hy:func:`coll? <hyrule.iterables.coll?>`
-    for this purpose.
+    ``x``. You can also use the Hyrule function :hy:func:`coll? <hyrule.coll?>` for this
+    purpose.
     """
 
     _extra_kwargs = ()

hy/pyops.hy

@@ -240,8 +240,8 @@ is equivalent to ``(+= count (+ n1 n2 n3)).``"
   provides its own syntactic sugar for this with a different macro, :hy:func:`cut <hy.pyops.cut>`.
 
   Note that ``.`` (:ref:`dot <dot>`) forms can also subscript. See also Hyrule's
-  :hy:func:`assoc <hyrule.collections.assoc>` to easily assign multiple elements of a
-  single collection.]]
+  :hy:func:`assoc <hyrule.assoc>` to easily assign multiple elements of a single
+  collection.]]
 
   (setv coll (get coll key1))
   (for [k keys]

hy/repl.py

@@ -236,10 +236,16 @@ class REPL(code.InteractiveConsole):
     A convenient way to use this class to interactively debug code is to insert the
     following in the code you want to debug::
 
-        (.run (hy.REPL :locals (locals)))
+        (.run (hy.REPL :locals {#** (globals) #** (locals)}))
 
-    Note that as with :func:`code.interact`, changes to ``(locals)`` inside the REPL are
-    not propagated back to the original scope."""
+    Or in Python:
+
+    .. code-block:: python
+
+       import hy; hy.REPL(locals = {**globals(), **locals()}).run()
+
+    Note that as with :func:`code.interact`, changes to local variables inside the
+    REPL are not propagated back to the original scope."""
 
     def __init__(self, spy=False, spy_delimiter=('-' * 30), output_fn=None, locals=None, filename="<stdin>", allow_incomplete=True):