updated README with installation and developer instructions; more prettifying

Author: reece

Makefile

@@ -46,7 +46,7 @@ publish: build ## publish package to PyPI
 #= FORMATTING, TESTING, AND CODE QUALITY
 
 .PHONY: cqa
-cqa: ## Run code quality assessments.
+cqa: ## Run code quality assessments
 	$(call INFO_MESSAGE, "Checking lock file consistency")
 	uv lock --locked
 	$(call INFO_MESSAGE, "Linting and reformatting files")

README.md

@@ -1,4 +1,4 @@
-# python-package
+# biocommons.example
 
 [![Release](https://img.shields.io/github/v/release/biocommons/python-package)](https://img.shields.io/github/v/release/biocommons/python-package)
 [![Build status](https://img.shields.io/github/actions/workflow/status/biocommons/python-package/main.yml?branch=main)](https://github.com/biocommons/python-package/actions/workflows/main.yml?query=branch%3Amain)
@@ -8,9 +8,88 @@
 
 Package Description
 
+This is a [biocommons](https://biocommons.org/) project.
+
 - **Github repository**: <https://github.com/biocommons/python-package/>
 - **Documentation** <https://biocommons.github.io/python-package/>
 
+## Python Package Installation
+
+Install from PyPI using one or more of the following:
+
+- `pip install biocommons.example`
+- `uv pip install biocommons.example`
+- Add `biocommons.example` to dependencies in `pyproject.toml` or `requirements.txt`
+
+## Developer Setup
+
+### Install Prerequisites
+
+These tools are required to get started:
+
+- [git](https://git-scm.com/): Version control system
+- [GNU make](https://www.gnu.org/software/make/): Current mechanism for consistent invocation of developer tools.
+- [uv](https://docs.astral.sh/uv/): An extremely fast Python package and project manager, written in Rust.
+
+#### MacOS or Linux Systems
+
+- [Install brew](https://brew.sh/)
+- `brew install git make uv`
+
+#### Linux (Debian-based systems)
+
+You may also install using distribution packages:
+
+    sudo apt install git make
+
+Then install uv using the [uv installation instructions](https://docs.astral.sh/uv/getting-started/installation/).
+
+### One-time developer setup
+
+Create a Python virtual environment, install dependencies, install pre-commit hooks, and install an editable package:
+
+    make devready
+
+### Development
+
+**N.B.** Developers are strongly encouraged to use `make` to invoke tools to
+ensure consistency with the CI/CD pipelines.  Type `make help` to see a list of
+supported targets.
+
+Try it:
+
+    $ source venv/bin/activate
+
+    $ python3 -m biocommons.example
+    Marvin says:
+    There's only one life-form as intelligent as me within thirty parsecs...
+
+    $ marvin-quote
+    Marvin says:
+    You think you've got problems? What are you supposed to do if you...
+
+    $ ipython
+    >>> from biocommons.example import __version__, get_quote_from_marvin
+    >>> __version__
+    '0.1.dev8+gd5519a8.d20211123'
+    >>> get_quote()
+    "The first ten million years were the worst, ...
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
 ## Getting started with your project
 
 ### 1. Create a New Repository

sbin/makefile-extract-documentation

@@ -1,4 +1,4 @@
-#!/usr/bin/env python
+#!/usr/bin/env python3
 """extract doc from a makefile"""
 
 # ############################################################################
@@ -11,10 +11,17 @@ import fileinput
 import re
 
 BOLD = "\033[1m"
-UNDERLINE = "\033[4m"
-SECTION_COLOR = "\033[93m"
-RESET = "\033[0m"
 COMMAND_COLOR = "\033[36m"
+HEADER_COLOR = "\033[32m"
+RESET = "\033[0m"
+SECTION_COLOR = "\033[93m"
+UNDERLINE = "\033[4m"
+
+print(f"""🌟🌟 {BOLD}{HEADER_COLOR}{UNDERLINE}biocommons conventional make targets{RESET} 🌟🌟
+
+Using these targets promots consistency between local development and ci/cd commands.
+
+usage: make [target ...])""")
 
 for line in fileinput.input():  # noqa: SIM115
     if m := re.match(r"#= (.+)", line):