Update documentation.

diff --git a/docs/pyutils.rst b/docs/pyutils.rst
index 9186f95ee81765b89bea7543de1dc7ce73a384db..0836f3149d834cbc5d583159aa47385a0019bd7f 100644 (file)
--- a/docs/pyutils.rst
+++ b/docs/pyutils.rst
@@ -1,35 +1,71 @@
 pyutils package
 ===============
 
+Introduction
+------------
+
 When I was writing little tools in Python and found myself implementing
 a generally useful pattern I stuffed it into a local library.  That
 library grew into pyutils: a set of collections, helpers and utilities
 that I find useful and hope you will too.
 
-Code is under `src/pyutils/
+The `LICENSE
+<https://wannabe.guru.org/gitweb/?p=pyutils.git;a=blob_plain;f=LICENSE;hb=HEAD>`__
+and `NOTICE
+<https://wannabe.guru.org/gitweb/?p=pyutils.git;a=blob_plain;f=NOTICE;hb=HEAD>`__
+files at the root of the project describe reusing this code and where
+everything came from.  Drop me a line if you are using this, find a
+bug, have a question, or have a suggestion:
+
+  --Scott Gasch ([email protected])
+
+Installation
+------------
+
+This project is now *pyutils* in PyPi, the default Python project index.  To install
+with pip::
+
+    pip install pyutils
+
+You'll get a few dependencies and this library.  The dependencies are high quality and
+stable:
+
+    - antlr4-python3-runtime: ANTLR grammer/parser runtime dependencies for the date
+      parsing grammar.
+    - bitstring: easy bitwise operations on long operands
+    - cloudpickle: a better version of Python's built in pickle used in the parallelize
+      code.
+    - holidays: a list of US and international holidays, used in the date parser.
+    - kazoo: a client side library with recipes for working with Apache Zookeeper, used
+      if and only if you enable Zookeeper-based configs.
+    - overrides: code decorator to mark and enforce method overrides.
+    - pytz: Python timezones, used in date parser and utils.
+
+Development
+-----------
+
+All of the project's code is located under `src/pyutils/
 <https://wannabe.guru.org/gitweb/?p=pyutils.git;a=tree;f=src/pyutils;h=e716e14b7a895e5c6206af90f4628bf756f040fe;hb=HEAD>`_.
-Most code includes inlint documentation and doctests.  I've tried to
+Most code includes inline documentation and doctests.  I've tried to
 organize it into logical packages based on the code's functionality.
-Note that when words would collide with a Python library or reserved
-word I've used a 'z' at the end, e.g. 'collectionz' instead of
-'collections', 'typez' instead of 'type', etc...
+Note that when words would collide with a Python standard library or
+reserved keyword I've used a 'z' at the end, e.g. 'collectionz'
+instead of 'collections', 'typez' instead of 'type', etc...
 
 There's some example code that uses various features of this project checked
-in under `examples/ <https://wannabe.guru.org/gitweb/?p=pyutils.git;a=tree;f=examples;h=d9744bf2b171ba7a9ff21ae1d3862b673647fff4;hb=HEAD>`_ that you can check out.
+in under `examples/ <https://wannabe.guru.org/gitweb/?p=pyutils.git;a=tree;f=examples;h=d9744bf2b171ba7a9ff21ae1d3862b673647fff4;hb=HEAD>`_ that you can check out.  See the `README <http://wannabe.guru.org/gitweb/?p=pyutils.git;a=blob_plain;f=examples/README;hb=HEAD>`__ in that directory for more information
+about what's there.
 
 Unit and integration tests are under `tests/
 <https://wannabe.guru.org/gitweb/?p=pyutils.git;a=tree;f=tests;h=8c303f23cd89b6d2e4fbf214a5c7dcc0941151b4;hb=HEAD>`_.
+
 To run all tests::
 
     cd tests/
     ./run_tests.py --all [--coverage]
 
-See the `README <https://wannabe.guru.org/gitweb/?p=pyutils.git;a=blob_plain;f=tests/README;hb=HEAD>`_ under `tests/` and the code of `run_tests.py` for more
-options / information about running tests.
-
-This package generates Sphinx docs which are available at:
-
-    https://wannabe.guru.org/pydocs/pyutils/pyutils.html
+See the `README <https://wannabe.guru.org/gitweb/?p=pyutils.git;a=blob_plain;f=tests/README;hb=HEAD>`__
+under `tests/` and the code of `run_tests.py` for more options / information about running tests.
 
 Package code is checked into a local git server and available to clone
 from git at https://wannabe.guru.org/git/pyutils.git or to view in a
@@ -43,16 +79,30 @@ development happened in a different git repo:
 
     https://wannabe.guru.org/gitweb/?p=python_utils.git;a=summary
 
-The `LICENSE
-<https://wannabe.guru.org/gitweb/?p=pyutils.git;a=blob_plain;f=LICENSE;hb=HEAD>`__
-and `NOTICE
-<https://wannabe.guru.org/gitweb/?p=pyutils.git;a=blob_plain;f=NOTICE;hb=HEAD>`__
-files at the root of the project describe reusing this code and where
-everything came from.  Drop me a line if you are using this, find a
-bug, have a question, or have a suggestion:
+To actually build the code (by which I mean type check it, lint it, package it, format
+it, etc...) you need some other dependencies installed:
 
-  --Scott Gasch ([email protected])
+    - black: I use black to auto-format the code
+    - coverage: used by the --coverage option of `run_tests.py`.
+    - flake8: a Python linter
+    - pylint: another Python linter
+    - sphinx: documenation generator
+    - setuptools: to build the project artifacts
+    - twine: to package and upload packages
+
+Documentation
+-------------
+
+The documentation you're browsing was created by Sphinx based largely on extracted code comments.
+It's available at:
+
+    https://wannabe.guru.org/pydocs/pyutils/pyutils.html
+
+Support
+-------
 
+If you find a bug or have a question, please email me ([email protected]).  I have not
+yet set up any more official bug tracker because there's no need yet.
 
 Subpackages
 -----------

diff --git a/tests/README b/tests/README
index 4553b739a8c40c2854c06caec1385e08c73b77a8..ab2729b3b4951f92717b4f88b7f682a212c9ea8d 100644 (file)
--- a/tests/README
+++ b/tests/README
@@ -2,7 +2,7 @@
 This directory contains the (non-doctest) testcode for pyutils (i.e. unit tests
 and integration tests).  It also contains a couple of helpers to run the tests.
 
-The easiest way to run the tests is, from within this tests/ directory, run:
+The easiest way to run the tests is, from within this tests/ directory, to run:
 
     ./run_tests_serially.sh -a
 
@@ -19,11 +19,12 @@ Or:
 
     ./run_tests.py -d
 
-Both of these runners store test output under ./test_output.
+Both of these runners store test output under tests/test_output.
 
 Both of them can optionally use coverage (pip install coverage) to generate a
-code coverage report:
+code coverage report at the end of testing:
 
     ./run_tests.py --all --coverage
 
-I use ./run_tests.py --all --coverage as a .git/hooks/pre-commit-hook.
+I use ./run_tests.py --all --coverage as a .git/hooks/pre-commit-hook during
+development.