Docs updates (#76)

pacrob · web-flow · commit e36af283c6eb · 2025-07-06T12:44:19.000+02:00
* updating docs and release tools

* more newsfragments

* towncrier commands in Makefile

* update towncrier underlines to match existing docs

* new underlinew

* new underlinew

* underlines

* underlines

* lint

* makefile cleanup

* remove readme.html stuff

* add build dev dependency and verify can build

* update dns tool dependency from aiodns to dnspython
diff --git a/.bumpversion.cfg b/.bumpversion.cfg
diff --git a/.gitignore b/.gitignore
@@ -58,9 +58,6 @@ coverage.xml
 # Sphinx documentation
 docs/_build/
 
-# File just for checking my RST syntax
-readme.html
-
 # PyBuilder
 target/
 
diff --git a/HISTORY.rst b/HISTORY.rst
@@ -1,6 +1,8 @@
 History
 =======
 
+.. towncrier release notes start
+
 0.0.7 (2019-5-8)
 ----------------
 
diff --git a/Makefile b/Makefile
@@ -11,20 +11,6 @@ endef
 export BROWSER_PYSCRIPT
 BROWSER := python -c "$$BROWSER_PYSCRIPT"
 
-help:
-	@echo "clean - remove all build, test, coverage and Python artifacts"
-	@echo "clean-build - remove build artifacts"
-	@echo "clean-pyc - remove Python file artifacts"
-	@echo "clean-test - remove test and coverage artifacts"
-	@echo "lint - check style with ruff"
-	@echo "test - run tests quickly with the default Python"
-	@echo "test-all - run tests on every Python version with tox"
-	@echo "coverage - check code coverage quickly with the default Python"
-	@echo "docs - generate Sphinx HTML documentation, including API docs"
-	@echo "release - package and upload a release"
-	@echo "dist - package"
-	@echo "install - install the package to the active Python's site-packages"
-
 clean: clean-build clean-pyc clean-test
 
 clean-build:
@@ -81,24 +67,41 @@ docs:
 servedocs: docs
 	watchmedo shell-command -p '*.rst' -c '$(MAKE) -C docs html' -R -D .
 
-readme.html: README.rst
-	rst2html.py README.rst > readme.html
-
 .PHONY: authors
 authors:
 	git shortlog --numbered --summary --email | cut -f 2 > AUTHORS
 
 dist: clean
-	python setup.py sdist
-	python setup.py bdist_wheel
+	python -m build
+	ls -l dist
 
 install: clean
 	python setup.py install
 
-bump:
-	bumpversion --tag-name "{new_version}" patch
-
-deploy-prep: clean authors readme.html docs dist
+# build newsfragments into release notes and verify docs build correctly
+notes: check-bump validate-newsfragments
+	# Let UPCOMING_VERSION be the version that is used for the current bump
+	$(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 docs
+	git commit -m "Compile release notes for v$(UPCOMING_VERSION)"
+
+deploy-prep: clean authors docs dist
 	@echo "Did you remember to bump the version?"
 	@echo "If not, run 'bumpversion {patch, minor, major}' and run this target again"
 	@echo "Don't forget to update HISTORY.rst"
+
+# helpers
+
+# verify that newsfragments are valid and towncrier can build them
+validate-newsfragments:
+	python ./newsfragments/validate_files.py
+	towncrier build --draft --version preview
+
+# verify that a bump argument is set to be passed to bump-my-version
+check-bump:
+ifndef bump
+	$(error bump must be set, typically: major, minor, patch, or devnum)
+endif
diff --git a/docs/multiaddr.rst b/docs/multiaddr.rst
@@ -5,9 +5,10 @@ Subpackages
 -----------
 
 .. toctree::
+   :maxdepth: 4
 
-    multiaddr.codecs
-    multiaddr.resolvers
+   multiaddr.codecs
+   multiaddr.resolvers
 
 Submodules
 ----------
@@ -16,39 +17,38 @@ multiaddr.exceptions module
 ---------------------------
 
 .. automodule:: multiaddr.exceptions
-    :members:
-    :undoc-members:
-    :show-inheritance:
+   :members:
+   :show-inheritance:
+   :undoc-members:
 
 multiaddr.multiaddr module
 --------------------------
 
 .. automodule:: multiaddr.multiaddr
-    :members:
-    :undoc-members:
-    :show-inheritance:
+   :members:
+   :show-inheritance:
+   :undoc-members:
 
 multiaddr.protocols module
 --------------------------
 
 .. automodule:: multiaddr.protocols
-    :members:
-    :undoc-members:
-    :show-inheritance:
+   :members:
+   :show-inheritance:
+   :undoc-members:
 
 multiaddr.transforms module
 ---------------------------
 
 .. automodule:: multiaddr.transforms
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
+   :members:
+   :show-inheritance:
+   :undoc-members:
 
 Module contents
 ---------------
 
 .. automodule:: multiaddr
-    :members:
-    :undoc-members:
-    :show-inheritance:
+   :members:
+   :show-inheritance:
+   :undoc-members:
diff --git a/multiaddr/multiaddr.py b/multiaddr/multiaddr.py
@@ -1,4 +1,3 @@
-# flake8: noqa: F811
 import collections.abc
 from collections.abc import Iterator, Sequence
 from typing import Any, Optional, TypeVar, Union, overload
diff --git a/newsfragments/65.feature.rst b/newsfragments/65.feature.rst
@@ -0,0 +1 @@
+Added support for CIDv1 format and improved sequence protocol handling with enhanced indexing and slicing operations.
diff --git a/newsfragments/65.internal.rst b/newsfragments/65.internal.rst
@@ -0,0 +1 @@
+Enhanced type safety with comprehensive type hints, improved validation, and expanded test coverage for better code reliability and maintainability.
diff --git a/newsfragments/68.feature.rst b/newsfragments/68.feature.rst
@@ -0,0 +1 @@
+Adds DNSADDR protocol support.
diff --git a/newsfragments/74.feature.rst b/newsfragments/74.feature.rst
@@ -0,0 +1 @@
+Adds support for p2p-circuit addresses.
diff --git a/newsfragments/75.docs.rst b/newsfragments/75.docs.rst
@@ -0,0 +1 @@
+Adds example of DNS address resolution.
diff --git a/newsfragments/README.md b/newsfragments/README.md
@@ -0,0 +1,29 @@
+This directory collects "newsfragments": short files that each contain
+a snippet of ReST-formatted text that will be added to the next
+release notes. This should be a description of aspects of the change
+(if any) that are relevant to users. (This contrasts with the
+commit message and PR description, which are a description of the change as
+relevant to people working on the code itself.)
+
+Each file should be named like `<ISSUE>.<TYPE>.rst`, where
+`<ISSUE>` is an issue number, and `<TYPE>` is one of:
+
+- `breaking`
+- `bugfix`
+- `deprecation`
+- `docs`
+- `feature`
+- `internal`
+- `misc`
+- `performance`
+- `removal`
+
+So for example: `123.feature.rst`, `456.bugfix.rst`
+
+If the PR fixes an issue, use that number here. If there is no issue,
+then open up the PR first and use the PR number for the newsfragment.
+
+Note that the `towncrier` tool will automatically
+reflow your text, so don't try to do any fancy formatting. Run
+`towncrier build --draft` to get a preview of what the release notes entry
+will look like in the final release notes.
diff --git a/newsfragments/validate_files.py b/newsfragments/validate_files.py
@@ -0,0 +1,43 @@
+#!/usr/bin/env python3
+
+# Towncrier silently ignores files that do not match the expected ending.
+# We use this script to ensure we catch these as errors in CI.
+
+import pathlib
+import sys
+
+ALLOWED_EXTENSIONS = {
+    ".breaking.rst",
+    ".bugfix.rst",
+    ".deprecation.rst",
+    ".docs.rst",
+    ".feature.rst",
+    ".internal.rst",
+    ".misc.rst",
+    ".performance.rst",
+    ".removal.rst",
+}
+
+ALLOWED_FILES = {
+    "validate_files.py",
+    "README.md",
+}
+
+THIS_DIR = pathlib.Path(__file__).parent
+
+num_args = len(sys.argv) - 1
+assert num_args in {0, 1}
+if num_args == 1:
+    assert sys.argv[1] in ("is-empty",)
+
+for fragment_file in THIS_DIR.iterdir():
+    if fragment_file.name in ALLOWED_FILES:
+        continue
+    elif num_args == 0:
+        full_extension = "".join(fragment_file.suffixes)
+        if full_extension not in ALLOWED_EXTENSIONS:
+            raise Exception(f"Unexpected file: {fragment_file}")
+    elif sys.argv[1] == "is-empty":
+        raise Exception(f"Unexpected file: {fragment_file}")
+    else:
+        raise RuntimeError(f"Strange: arguments {sys.argv} were validated, but not found")
diff --git a/pyproject.toml b/pyproject.toml

-Original file line number
+Diff line change
@@ @@ -1,6 +1,8 @@ @@
 History
 =======
 +.. towncrier release notes start
++
 .0.7 (2019-5-8)
 ----------------
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,3 @@`
`1`		`-# flake8: noqa: F811`
`2`	`1`	`import collections.abc`
`3`	`2`	`from collections.abc import Iterator, Sequence`
`4`	`3`	`from typing import Any, Optional, TypeVar, Union, overload`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+Added support for CIDv1 format and improved sequence protocol handling with enhanced indexing and slicing operations.`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+Enhanced type safety with comprehensive type hints, improved validation, and expanded test coverage for better code reliability and maintainability.`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+Adds support for p2p-circuit addresses.`