Merge pull request #12 from slott56/dev/3.1

Dev/3.1

.gitignore

@@ -1,3 +1,15 @@
 
 dev.sh
-.idea/*
+.idea
+pyweb-3.0.py
+__pycache__
+test/__pycache__/*.pyc
+tests/.svn/*
+py_web_tool.egg-info/*
+*.pyc
+*.aux
+*.out
+*.toc
+v2_test
+.tox
+pyweb-3.0.py

.nojekyll

@@ -1 +1,2 @@
 
+

MANIFEST.in

@@ -1,3 +1,4 @@
-include *.w *.css *.html *.conf *.rst
-include test/*.w test/*.css test/*.html test/*.conf test/*.py
+include src/*.w src/*.css src/*.html src/*.conf src/*.rst src/*.py
+include bootstrap/*.py
+include tests/*.w tests/*.css tests/*.html tests/*.conf tests/*.py
 include jedit/*.xml

Makefile

@@ -0,0 +1,56 @@
+# Makefile for py-web-tool.
+# Requires a pyweb-3.0.py (untouched) to bootstrap the current version.
+
+SOURCE_PYLPWEB = src/pyweb.w src/intro.w src/overview.w src/impl.w src/tests.w src/todo.w src/done.w src/language.w src/usage.w
+TEST_PYLPWEB = tests/pyweb_test.w tests/intro.w tests/unit.w tests/func.w tests/scripts.w	
+EXAMPLES_PYLPWEB = examples/hello_world_latex.w examples/hello_world_rst.w ackermanns.w
+DOCUTILS_PYLPWEB = docutils.conf pyweb.css page-layout.css
+
+.PHONY : test
+
+# Note the bootstrapping new version from version 3.0 as baseline.
+# Handy to keep this *outside* the project's Git repository.
+# Note that the bootstrap 3.0 version doesn't support the -o option.
+PYLPWEB_BOOTSTRAP=${PWD}/bootstrap/pyweb.py
+
+test : $(SOURCE_PYLPWEB) $(TEST_PYLPWEB)
+	cd src && python3 $(PYLPWEB_BOOTSTRAP) -xw pyweb.w 
+	python3 src/pyweb.py tests/pyweb_test.w -o tests
+	PYTHONPATH=${PWD}/src pytest
+	python3 src/pyweb.py tests/pyweb_test.w -xt -o tests
+	rst2html.py tests/pyweb_test.rst tests/pyweb_test.html
+	mypy --strict --show-error-codes src
+
+doc : src/pyweb.html
+
+build : src/pyweb.py src/tangle.py src/weave.py src/pyweb.html
+
+examples : examples/hello_world_latex.tex examples/hello_world_rst.html examples/ackermanns.html
+
+src/pyweb.py src/pyweb.rst : $(SOURCE_PYLPWEB)
+	cd src && python3 $(PYLPWEB_BOOTSTRAP) pyweb.w 
+
+src/pyweb.html : src/pyweb.rst $(DOCUTILS_PYLPWEB)
+	rst2html.py $< $@
+
+tests/pyweb_test.rst : src/pyweb.py $(TEST_PYLPWEB)
+	python3 src/pyweb.py tests/pyweb_test.w -o tests
+
+tests/pyweb_test.html : tests/pyweb_test.rst $(DOCUTILS_PYLPWEB)
+	rst2html.py $< $@
+
+examples/hello_world_rst.rst : examples/hello_world_rst.w
+	python3 src/pyweb.py -w rst examples/hello_world_rst.w -o examples
+
+examples/hello_world_rst.html : examples/hello_world_rst.rst $(DOCUTILS_PYLPWEB)
+	rst2html.py $< $@
+
+examples/hello_world_latex.tex : examples/hello_world_latex.w
+	python3 src/pyweb.py -w latex examples/hello_world_latex.w -o examples
+
+examples/ackermanns.rst : examples/ackermanns.w
+	python3 src/pyweb.py -w rst examples/ackermanns.w -o examples
+	python -m doctest examples/ackermanns.py
+
+examples/ackermanns.html : examples/ackermanns.rst $(DOCUTILS_PYLPWEB)
+	rst2html.py $< $@

README

@@ -1,4 +1,4 @@
-pyWeb 3.0: In Python, Yet Another Literate Programming Tool
+pyWeb 3.1: In Python, Yet Another Literate Programming Tool
 
 Literate programming is an attempt to reconcile the opposing needs
 of clear presentation to people with the technical issues of 
@@ -14,72 +14,96 @@ It is independent of any particular document markup or source language.
 Is uses a simple set of markup tags to define chunks of code and 
 documentation.
 
-The ``pyweb.w`` file is the source for the various pyweb module and script files.
+The ``pyweb.w`` file is the source for the various ``pyweb`` module and script files.
 The various source code files are created by applying a
 tangle operation to the ``.w`` file.  The final documentation is created by
 applying a weave operation to the ``.w`` file.
 
 Installation
 -------------
 
+This requires Python 3.10.
+
+This is not (currently) hosted in PyPI. Instead of installing it with PIP,
+clone the GitHub repository or download the distribution kit.
+
+Install pyweb "manually" using the provided ``setup.py``.
+
 ::
 
-    python3 setup.py install
+    python setup.py install
+
+This will install the ``pyweb`` module.
 
-This will install the pyweb module.
+Produce Documentation
+---------------------
 
-Document production
---------------------
+The supplied documentation uses RST markup; it requires docutils.
 
-The supplied documentation uses RST markup and requires docutils.
+::
+
+    python3 -m pip install docutils
 
 ::
 
-	python3 -m pyweb pyweb.w
-	rst2html.py pyweb.rst pyweb.html
+	python3 -m pyweb src/pyweb.w -o src
+	rst2html.py src/pyweb.rst src/pyweb.html
 
 Authoring
 ---------
 
-The pyweb document describes the simple markup used to define code chunks
+The ``pyweb.html`` document describes the markup used to define code chunks
 and assemble those code chunks into a coherent document as well as working code.
+You'll create a ``.w`` file with documentation and code.
 
 If you're a JEdit user, the ``jedit`` directory can be used
-to configure syntax highlighting that includes PyWeb and RST.
+to configure syntax highlighting that includes **py-web-tool** and RST.
 
 Operation
 ---------
 
-You can then run pyweb with
+After installation and authoring, you can then run **py-web-tool** with the following 
+command
 
 ::
 
-    python3 -m pyweb pyweb.w 
+    python3 -m pyweb src/pyweb.w -o src 
+
+This will create the various output files from the source ```.w`` file.
 
-This will create the various output files from the source .w file.
+-   ``pyweb.rst`` is the final woven document. This can be run through docutils for publication.
 
--   ``pyweb.html`` is the final woven document.
+-   ``pyweb.py``, ``tangle.py``, ``weave.py`` are the tangled code files.
 
--   ``pyweb.py``, ``tangle.py``, ``weave.py``, ``README``, ``setup.py`` and ``MANIFEST.in`` 
-	``.nojekyll`` and ``index.html`` are tangled output files.
+All of the files are produced from a single source.
 
 Testing
 -------
 
-The test directory includes ``pyweb_test.w``, which will create a 
+The ``tests`` directory includes ``pyweb_test.w``, which will create a 
 complete test suite.
+You can create this with the following command
 
-This weaves a ``pyweb_test.html`` file.
+::
+
+    python3 -m pyweb tests/pyweb_test.w -o tests 
+
+This weaves a ``tests/pyweb_test.rst`` file. This can be run through docutils for publication.
 
 This tangles several test modules:  ``test.py``, ``test_tangler.py``, ``test_weaver.py``,
-``test_loader.py`` and ``test_unit.py``.  Running the ``test.py`` module will include and
-execute all tests.
+``test_loader.py``, ``test_unit.py``, and ``test_scripts.py``.  
 
-::
+Use **pytest** to run all the tests.
+
+Here's a typical sequence, used during development:
 
-	cd test
-	python3 -m pyweb pyweb_test.w
-	PYTHONPATH=.. python3 test.py
-	rst2html.py pyweb_test.rst pyweb_test.html
+::
 
+	python3 bootstrap/pyweb.py -xw src/pyweb.w -o src 
+	python3 src/pyweb.py tests/pyweb_test.w -o tests
+	PYTHONPATH=${PWD}/src pytest
+	rst2html.py tests/pyweb_test.rst tests/pyweb_test.html
+    mypy --strict src
 
+Note that a previous release, untouched, is saved in the ``bootstrap`` directory.
+This is **not** changed during development, since **py-web-tool** is written with **py-web-tool**.