merge template, fill vars, run lint

Author: pacrob

.bumpversion.cfg

@@ -121,15 +121,11 @@ docs: &docs
         command: |
           python -m pip install --upgrade pip
           python -m pip install tox
-    # latexpdf turned off for now - won't build due to long line lengths
-    # - run:
-    #     name: install latexpdf dependencies
-    #     command: |
-    #       sudo apt-get update
-    #       sudo apt-get install latexmk tex-gyre texlive-fonts-extra texlive-xetex xindy
     - run:
         name: run tox
         command: python -m tox run -r
+    - store_artifacts:
+          path: /home/circleci/repo/docs/_build
     - save_cache:
         paths:
           - .tox

.circleci/config.yml

@@ -1,4 +1,4 @@
-exclude: '.project-template|docs/conf.py|.bumpversion.cfg'
+exclude: '.project-template|docs/conf.py'
 repos:
 -   repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v4.5.0

.pre-commit-config.yaml

@@ -3,7 +3,7 @@ version: 2
 build:
   os: ubuntu-22.04
   tools:
-    python: "3.9"
+    python: "3.10"
 
 sphinx:
   configuration: docs/conf.py
@@ -16,9 +16,6 @@ python:
       extra_requirements:
         - docs
 
-# Build all formats for RTD Downloads - htmlzip, pdf, epub
-# formats: all
-# Turning off pdf for now - won't build due to long line lengths
 formats:
   - epub
   - htmlzip

.readthedocs.yaml

@@ -5,15 +5,16 @@ CURRENT_SIGN_SETTING := $(shell git config commit.gpgSign)
 help:
 	@echo "clean-build - remove build artifacts"
 	@echo "clean-pyc - remove Python file artifacts"
+	@echo "clean - run clean-build and clean-pyc"
+	@echo "dist - build package and cat contents of the dist directory"
 	@echo "lint - fix linting issues with pre-commit"
 	@echo "test - run tests quickly with the default Python"
+	@echo "benchmark - run benchmark tests"
 	@echo "docs - generate docs and open in browser (linux-docs for version on linux)"
 	@echo "autobuild-docs - live update docs when changes are saved"
-	@echo "notes - consume towncrier newsfragments/ and update release notes in docs/"
-	@echo "release - package and upload a release (does not run notes target)"
-	@echo "dist - package"
-
-clean: clean-build clean-pyc
+	@echo "package-test - build package and install it in a venv for manual testing"
+	@echo "notes - consume towncrier newsfragments and update release notes in docs - requires bump to be set"
+	@echo "release - package and upload a release (does not run notes target) - requires bump to be set"
 
 clean-build:
 	rm -fr build/
@@ -26,6 +27,12 @@ clean-pyc:
 	find . -name '*~' -exec rm -f {} +
 	find . -name '__pycache__' -exec rm -rf {} +
 
+clean: clean-build clean-pyc
+
+dist: clean
+	python -m build
+	ls -l dist
+
 lint:
 	@pre-commit run --all-files --show-diff-on-failure || ( \
 		echo "\n\n\n * pre-commit should have fixed the errors above. Running again to make sure everything is good..." \
@@ -38,66 +45,72 @@ test:
 benchmark:
 	python -m tox run -e benchmark
 
+# docs commands
+
+docs: check-docs
+	open docs/_build/html/index.html
+
+linux-docs: check-docs
+	xdg-open docs/_build/html/index.html
+
 autobuild-docs:
 	sphinx-autobuild --open-browser docs docs/_build/html
 
-build-docs:
-	sphinx-apidoc -o docs/ . setup.py "*conftest*" "tests" "web3/tools/*"
-	$(MAKE) -C docs clean
-	$(MAKE) -C docs html
-	$(MAKE) -C docs doctest
-
-build-docs-ci:
-	# pdf turned off for now - long line lengths break the build
-	# $(MAKE) -C docs latexpdf
-	$(MAKE) -C docs epub
+# docs helpers
 
 validate-newsfragments:
 	python ./newsfragments/validate_files.py
 	towncrier build --draft --version preview
 
 check-docs: build-docs validate-newsfragments
 
+build-docs:
+	sphinx-apidoc -o docs/ . setup.py "*conftest*"
+	$(MAKE) -C docs clean
+	$(MAKE) -C docs html
+	$(MAKE) -C docs doctest
+
 check-docs-ci: build-docs build-docs-ci validate-newsfragments
 
-docs: check-docs
-	open docs/_build/html/index.html
+build-docs-ci:
+	$(MAKE) -C docs epub
 
-linux-docs: check-docs
-	xdg-open docs/_build/html/index.html
+# release commands
 
-check-bump:
-ifndef bump
-	$(error bump must be set, typically: major, minor, patch, or devnum)
-endif
+package-test: clean
+	python -m build
+	python scripts/release/test_package.py
 
-notes: check-bump validate-newsfragments
+notes: check-bump
 	# Let UPCOMING_VERSION be the version that is used for the current bump
-	$(eval UPCOMING_VERSION=$(shell bumpversion $(bump) --dry-run --list | grep new_version= | sed 's/new_version=//g'))
+	$(eval UPCOMING_VERSION=$(shell bump-my-version bump --dry-run $(bump) -v | awk -F"'" '/New version will be / {print $$2}'))
 	# Now generate the release notes to have them included in the release commit
 	towncrier build --yes --version $(UPCOMING_VERSION)
 	# Before we bump the version, make sure that the towncrier-generated docs will build
 	make build-docs
 	git commit -m "Compile release notes for v$(UPCOMING_VERSION)"
 
-release: check-bump clean
-	# require that upstream is configured for ethereum/web3.py
-	@git remote -v | grep "upstream[[:space:]][email protected]:ethereum/web3.py.git (push)\|upstream[[:space:]]https://github.com/ethereum/web3.py (push)"
-	# verify that docs build correctly
+release: check-bump check-git clean
+	# verify that notes command ran correctly
 	./newsfragments/validate_files.py is-empty
-	make build-docs
 	CURRENT_SIGN_SETTING=$(git config commit.gpgSign)
 	git config commit.gpgSign true
-	bumpversion $(bump)
+	bump-my-version bump $(bump)
 	python -m build
+	git config commit.gpgSign "$(CURRENT_SIGN_SETTING)"
 	git push upstream && git push upstream --tags
 	twine upload dist/*
-	git config commit.gpgSign "$(CURRENT_SIGN_SETTING)"
 
-dist: clean
-	python -m build
-	ls -l dist
+# release helpers
 
-package: clean
-	python -m build
-	python web3/scripts/release/test_package.py
+check-bump:
+ifndef bump
+	$(error bump must be set, typically: major, minor, patch, or devnum)
+endif
+
+check-git:
+	# require that upstream is configured for ethereum/web3.py
+	@if ! git remote -v | grep "upstream[[:space:]][email protected]:ethereum/web3.py.git (push)\|upstream[[:space:]]https://github.com/ethereum/web3.py (push)"; then \
+		echo "Error: You must have a remote named 'upstream' that points to 'web3.py'"; \
+		exit 1; \
+	fi

Makefile

@@ -12,14 +12,18 @@ web3.py allows you to interact with the Ethereum blockchain using Python, enabli
 
 - Python 3.8+ support
 
-______________________________________________________________________
+## Installation
+
+```sh
+python -m pip install web3
+```
 
-## Quickstart
+## Documentation
 
 [Get started in 5 minutes](https://web3py.readthedocs.io/en/latest/quickstart.html) or
 [take a tour](https://web3py.readthedocs.io/en/latest/overview.html) of the library.
 
-## Documentation
+View the [change log](https://web3py.readthedocs.io/en/latest/release_notes.html).
 
 For additional guides, examples, and APIs, see the [documentation](https://web3py.readthedocs.io/en/latest/).
 

README.md

@@ -55,6 +55,7 @@ Finally, install all development dependencies:
 .. code:: sh
 
     $ pip install -e ".[dev]"
+    $ pre-commit install
 
 
 Using Docker
@@ -424,93 +425,82 @@ published and the test runs are updated to use the new stable version.
 Releasing
 ~~~~~~~~~
 
-Final Test Before Each Release
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Releases are typically done from the ``main`` branch, except when releasing a beta (in
+which case the beta is released from ``main``, and the previous stable branch is
+released from said branch).
 
-Before releasing a new version, build and test the package that will be released.
-There's a script to build and install the wheel locally, then generate a temporary
-virtualenv for smoke testing:
+Final test before each release
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-.. code:: sh
-
-    $ git checkout main && git pull
-
-    $ make package
+Before releasing a new version, build and test the package that will be released:
 
-    # in another shell, navigate to the virtualenv mentioned in output of ^
-
-    # load the virtualenv with the packaged web3.py release
-    $ source package-smoke-test/bin/activate
-
-    # smoke test the release
-    $ pip install ipython
-    $ ipython
-    >>> from web3 import Web3, IPCProvider
-    >>> w3 = Web3(IPCProvider(provider_url))
-    >>> w3.is_connected()
-    >>> ...
+.. code:: sh
 
+    git checkout main && git pull
+    make package-test
 
-Verify The Latest Documentation
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+This will build the package and install it in a temporary virtual environment. Follow
+the instructions to activate the venv and test whatever you think is important.
 
-To preview the documentation that will get published:
+Review the documentation that will get published:
 
 .. code:: sh
 
-    $ make docs
+    make docs
 
-
-Preview The Release Notes
-^^^^^^^^^^^^^^^^^^^^^^^^^
+Validate and preview the release notes:
 
 .. code:: sh
 
-   $ towncrier build --draft
-
+    make validate-newsfragments
 
-Compile The Release Notes
-^^^^^^^^^^^^^^^^^^^^^^^^^
+Build the release notes
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-After confirming that the release package looks okay, compile the release notes:
+Before bumping the version number, build the release notes. You must include the part of
+the version to bump (see below), which changes how the version number will show in the
+release notes.
 
 .. code:: sh
 
-    $ make notes bump=$$VERSION_PART_TO_BUMP$$
-
+    make notes bump=$$VERSION_PART_TO_BUMP$$
 
-You may need to fix up any broken release note fragments before committing. Keep
-running ``make build-docs`` until it passes, then commit and carry on.
+If there are any errors, be sure to re-run make notes until it works.
 
+Push the release to github & pypi
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Push The Release to GitHub & PyPI
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-After committing the compiled release notes and pushing them to the main
-branch, release a new version:
+After confirming that the release package looks okay, release a new version:
 
 .. code:: sh
 
-    $ make release bump=$$VERSION_PART_TO_BUMP$$
+    make release bump=$$VERSION_PART_TO_BUMP$$
+
+This command will:
 
+- Bump the version number as specified in ``.pyproject.toml`` and ``setup.py``.
+- Create a git commit and tag for the new version.
+- Build the package.
+- Push the commit and tag to github.
+- Push the new package files to pypi.
 
-Which Version Part to Bump
-^^^^^^^^^^^^^^^^^^^^^^^^^^
+Which version part to bump
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-The version format for this repo is ``{major}.{minor}.{patch}`` for
-stable, and ``{major}.{minor}.{patch}-{stage}.{devnum}`` for unstable
-(``stage`` can be alpha or beta).
+``$$VERSION_PART_TO_BUMP$$`` must be one of: ``major``, ``minor``, ``patch``, ``stage``,
+or ``devnum``.
 
-During a release, specify which part to bump, like
-``make release bump=minor`` or ``make release bump=devnum``.
+The version format for this repo is ``{major}.{minor}.{patch}`` for stable, and
+``{major}.{minor}.{patch}-{stage}.{devnum}`` for unstable (``stage`` can be alpha or
+beta).
 
-If you are in an alpha version, ``make release bump=stage`` will bump to beta.
-If you are in a beta version, ``make release bump=stage`` will bump to a stable
-version.
+If you are in a beta version, ``make release bump=stage`` will switch to a stable.
 
-To issue an unstable version when the current version is stable, specify the new
-version explicitly, like ``make release bump="--new-version 4.0.0-alpha.1 devnum"``.
+To issue an unstable version when the current version is stable, specify the new version
+explicitly, like ``make release bump="--new-version 4.0.0-alpha.1"``
 
+You can see what the result of bumping any particular version part would be with
+``bump-my-version show-bump``
 
 .. _Python Discord server: https://discord.gg/GHryRvPB84
 .. _style guide: https://github.com/ethereum/snake-charmers-tactical-manual/blob/main/style-guide.md

docs/contributing.rst

@@ -16,6 +16,9 @@ block data, and a variety of other use cases.
 For project updates, follow `@EthereumPython`_ and sign up
 for new post notifications on the `blog`_.
 
+.. toctree::
+    :maxdepth: 1
+    :caption: Community
 
 Getting Started
 ---------------