Merge pull request #271 from gilch/doc-once-over

Doc updates for release

conftest.py

@@ -99,3 +99,5 @@ def __contains__(self, item):
     parsers=[ParseLissp(optionflags=ELLIPSIS)],
     filenames=Globs("*.md", "*.rst", "*.lissp"),
 ).pytest()
+
+# RELEASE: Run all tests.

docs/command_line_reference.rst

@@ -14,6 +14,8 @@ also install the ``lissp`` command-line tool for running Lissp code.
 This is a convenience executable for starting ``python -m hissp``,
 whose minimal options were modeled after Python's most commonly used:
 
+.. RELEASE: Update (Hissp X.X.X) line.
+
 .. code-block:: Text
 
    usage: lissp [-h] [-i] [-c cmd] [file] [args [args ...]]

docs/conf.py

@@ -99,3 +99,5 @@
 html_static_path = ["_static"]
 
 intersphinx_mapping = {"python": ("https://docs.python.org/3.10", None)}
+
+# RELEASE: Make sure to clean build docs and check for errors.

docs/lissp_whirlwind_tour.rst

@@ -9,6 +9,7 @@
    ...                 __import__('hissp')._macro_)))
 
 .. TODO: Interactive via web repl?
+.. RELEASE: Update the ;;;; Installation section.
 
 Lissp Whirlwind Tour
 ====================

docs/macro_tutorial.rst

@@ -11,7 +11,6 @@ Macro Tutorial
 ##############
 
 .. TODO: be sure to demonstrate hissp.compiler..ENV and hissp.compiler..readerless somewhere
-.. TODO: be sure to demonstrate a recursive macro somewhere
 
 Lisp is a higher-level language than Python,
 in the same sense that Python is a higher-level language than C,
@@ -2741,9 +2740,8 @@ which have the same issue.
 A simple basic syntax means there are relatively few edge cases you have to be aware of.
 
 Hissp is so simple that a full code-walking macro would only have to pre-expand all macros,
-and handle atoms, calls, ``quote``, and ``lambda``.
-
-.. TODO: Which we will be demonstrating later!
+and handle atoms, calls, ``quote``, and ``lambda``,
+which we will be demonstrating later!
 
 If you add Python injections to the list,
 then you also have to handle the entirety of all Python expressions.
@@ -6717,8 +6715,6 @@ A lot of programming comes down to restructuring data like this.
 If you've made it this far,
 show off your solutions in the Hissp Community Chat!
 
-.. TODO: and that's how the bundled d# version works.
-
 .. TODO: advanced techniques from A Slice o Python?
    Let's review. This section covered a number of advanced techniques:
    - Brackets in symbols.
@@ -6768,11 +6764,7 @@ show off your solutions in the Hissp Community Chat!
 
 .. TODO: preconditions?
 
-.. TODO: base 6, tau
-
 .. TODO: defmacro/g defmacro!
-.. TODO: destructuring bind (iterable only?)
-.. TODO: destructuring lambda (iterable only?)
 
 .. TODO: one-shot self-referential data structure using reader macros
              See http://www.lispworks.com/documentation/HyperSpec/Body/02_dho.htm

docs/primer.rst

@@ -55,6 +55,8 @@ Confirm your Python version with
 
 (Re-)install the Hissp version matching this document with
 
+.. RELEASE: Rewrite to install from PyPI.
+
 .. code-block:: console
 
    $ python -m pip install --upgrade --force-reinstall git+https://github.com/gilch/hissp

setup.py

@@ -67,3 +67,7 @@
 )
 # Build dist and install:
 # python setup.py bdist_wheel && pip install --force-reinstall setup\dist\hissp-*.whl
+
+# RELEASE: Double-check setup data.
+# RELEASE: Clean build macros.py and make sure it's in the .whl.
+# RELEASE: Inspect all files in the .whl.

src/hissp/__init__.py

@@ -88,7 +88,7 @@
 with __import__("contextlib").suppress(ImportError):
     from hissp.macros import _macro_
 
-VERSION = "0.5.dev"
+VERSION = "0.5.dev"  # RELEASE
 
 
 def prelude(env):

src/hissp/__main__.py

@@ -1,4 +1,4 @@
-# Copyright 2020, 2021 Matthew Egan Odendahl
+# Copyright 2020, 2021, 2024 Matthew Egan Odendahl
 # SPDX-License-Identifier: Apache-2.0
 """
 Hissp's command-line interface.

src/hissp/macros.lissp

@@ -3,35 +3,28 @@
 
 "Hissp's bundled `tag` and `macro` metaprograms.
 
-To help keep definitions and `expansion`\\ s manageable in
-complexity, these metaprograms lack some of the extra features their
-equivalents have in Python or in other Lisps. They are not intended to
-be a standard library for general use, but do bring Hissp up to a basic
-standard of utility without adding dependencies, which may suffice in
-some cases.
-
-Because of deliberate design restrictions, there are no dependencies in
-their expansions either, meaning the compiled output of the bundled
-macros need not have Hissp installed to work, only the Python standard
-library. All helper code must therefore be inlined, resulting in larger
-expansions than might otherwise be necessary.
+While completely optional, these bring Hissp up to a minimal standard of
+practical utility without adding dependencies. As a convenience, they
+are automatically made available `unqualified` in the Lissp `REPL`, but
+this is not true of modules.
+
+Hissp's `standalone property` means the compiled output of code written
+using these metaprograms need not have Hissp installed at run time to
+work, only the Python standard library. All helper code must therefore
+be inlined, resulting in larger expansions than might otherwise be
+necessary.
 
 They also have no prerequisite initialization, beyond what is available
 in a standard Python module. For example, a ``_macro_`` namespace need
 not be available for ``defmacro``. It's smart enough to check for the
 presence of ``_macro_`` (at compile time) in its expansion context, and
 inline the initialization code when required.
 
-As a convenience, the bundled macros are automatically made available
-`unqualified` in the Lissp `REPL`, but this does not apply to modules. A
-Hissp module with better alternatives need not use the bundled macros at
-all.
-
 With the exception of `mix`, which is a `text macro` specifically made
 for creating a `Python injection`, the other metaprograms eschew
 expansions of any of their arguments to a `Python injection` (other than
-the standard `symbol` or `string literal fragment` cases), relying only
-on the built-in special forms ``quote`` and ``lambda``, which makes
+the `standard` `symbol` or `string literal fragment` cases), relying
+only on the built-in special forms ``quote`` and ``lambda``, which makes
 their expansions compatible with advanced rewriting macros that process
 the Hissp expansions of other macros.
 
@@ -2716,7 +2709,6 @@ See `hissp.macros`.
   ;; such as a global variable name or module attribute.
   ;; This will be written into the wrapper body.
   ;;
-  ;;
   ;; .. code-block:: REPL
   ;;
   ;;    #> (defun greet ()
@@ -4539,6 +4531,5 @@ sentinel#
     `(avow ,expr ,predicate ,@args)
     expr))
 
-;;; Don't let the size of this file intimidate you. Most of the lines
-;;; are documentation. After you remove the comments, docstrings, and
-;;; blank lines, only about 300 lines of actual code remain.
+;;; Don't let the size of this file intimidate you!
+;;; Only about 10% of the lines are actual source code.

src/hissp/munger.py

@@ -1,4 +1,4 @@
-# Copyright 2019, 2020, 2021 Matthew Egan Odendahl
+# Copyright 2019, 2020, 2021, 2024 Matthew Egan Odendahl
 # SPDX-License-Identifier: Apache-2.0
 """
 Lissp's `symbol token` munger.

src/hissp/repl.py

@@ -1,4 +1,4 @@
-# Copyright 2020, 2021, 2022 Matthew Egan Odendahl
+# Copyright 2020, 2021, 2022, 2024 Matthew Egan Odendahl
 # SPDX-License-Identifier: Apache-2.0
 """
 The Lissp Read-Evaluate-Print Loop. For interactive use.