Fix exception tree documentation; parameterize publish script so it c…

…an publish to a non-local IPFS server

docs/index.md

@@ -1,5 +1,5 @@
-Python IPFS HTTP Client's documentation!
-================================
+Python IPFS HTTP Client
+=======================
 
 Contents
 --------

docs/publish.py

@@ -1,41 +1,66 @@
 #!/usr/bin/python3
 import os
 import sys
-__dir__ = os.path.dirname(__file__)
-sys.path.insert(0, os.path.join(__dir__, ".."))
+import typing as ty
+
+script_dir = os.path.dirname(os.path.realpath(__file__))
+sys.path.insert(0, os.path.join(script_dir, ".."))
 
 import sphinx.cmd.build
 import ipfshttpclient
 
-# Ensure working directory is script directory
-os.chdir(__dir__)
+os.chdir(script_dir)
+
+
+def main(argv: ty.List[str]) -> int:
+	if len(argv) >= 1:
+		ipns_key = argv[0]
+	else:
+		ipns_key = None
 
-def main(argv=sys.argv[1:], program=sys.argv[0]):
-	if len(argv) != 1:
-		print("Usage: {0} [IPNS-key]".format(os.path.basename(program)))
+		print("Usage: {0} [IPNS-key]".format(os.path.basename(__file__)))
 		print()
 		print("!! Continuing without publishing to IPNS !!")
 		print()
-
+
+	ipfs_api_address: str = os.getenv('IPFS_API_MULTI_ADDR', str(ipfshttpclient.DEFAULT_ADDR))
+	ipfs_api_username: ty.Optional[str] = os.getenv('IPFS_API_USERNAME', None)
+	ipfs_api_password: ty.Optional[str] = os.getenv('IPFS_API_PASSWORD', None)
+
+	return publish(
+		ipfs_api_address=ipfs_api_address,
+		ipfs_api_username=ipfs_api_username,
+		ipfs_api_password=ipfs_api_password,
+		ipns_key=ipns_key
+	)
+
+
+def publish(
+		ipfs_api_address: str,
+		ipfs_api_username: ty.Optional[str],
+		ipfs_api_password: ty.Optional[str],
+		ipns_key: ty.Optional[str]) -> int:
 	# Invoke Sphinx like the Makefile does
 	result = sphinx.cmd.build.build_main(["-b", "html", "-d", "build/doctrees", ".", "build/html"])
 	if result != 0:
 		return result
 
 	print()
-	print("Exporting files to IPFS…")
-	client = ipfshttpclient.connect()
+	print(f"Exporting files to IPFS server at {ipfs_api_address}…")
+	client = ipfshttpclient.connect(addr=ipfs_api_address, username=ipfs_api_username, password=ipfs_api_password)
 	hash_docs = client.add("build/html", recursive=True, raw_leaves=True, pin=False)[-1]["Hash"]
 	hash_main = client.object.new("unixfs-dir")["Hash"]
 	hash_main = client.object.patch.add_link(hash_main, "docs", hash_docs)["Hash"]
 	client.pin.add(hash_main)
-	print("Final IPFS path: /ipfs/{0}".format(hash_main))
+
+	print("Final IPFS path:")
+	print(f'  /ipfs/{hash_main}')
+	print(f'  https://ipfs.io/ipfs/{hash_main}')
 
-	if len(argv) == 1:
-		key = argv[0]
+	if ipns_key:
 		print()
 		print("Exporting files to IPNS…")
-		name_main = client.name.publish(hash_main, key=key)["Name"]
+		name_main = client.name.publish(hash_main, key=ipns_key)["Name"]
 		print("Final IPNS path: /ipns/{0}".format(name_main))
 
 		print()
@@ -44,5 +69,6 @@ def main(argv=sys.argv[1:], program=sys.argv[0]):
 
 	return 0
 
+
 if __name__ == "__main__":
-	sys.exit(main())
+	sys.exit(main(sys.argv[1:]))

ipfshttpclient/exceptions.py

@@ -1,25 +1,26 @@
 """
-The class hierarchy for exceptions is:
-
-	Warning
-	 └── VersionMismatch
-
-	Error
-	 ├── AddressError
-	 ├── EncoderError
-	 │    ├── EncoderMissingError
-	 │    ├── EncodingError
-	 │    └── DecodingError
-	 ├── CommunicationError
-	 │    ├── ProtocolError
-	 │    ├── StatusError
-	 │    ├── ErrorResponse
-	 │    │    └── PartialErrorResponse
-	 │    ├── ConnectionError
-	 │    └── TimeoutError
-	 └── MatcherSpecInvalidError
+The class hierarchy for exceptions is::
+
+    Exception
+     ├── Warning
+     │    └── VersionMismatch
+     └── Error
+          ├── AddressError
+          ├── EncoderError
+          │    ├── EncoderMissingError
+          │    ├── EncodingError
+          │    └── DecodingError
+          ├── CommunicationError
+          │    ├── ProtocolError
+          │    ├── StatusError
+          │    ├── ErrorResponse
+          │    │    └── PartialErrorResponse
+          │    ├── ConnectionError
+          │    └── TimeoutError
+          └── MatcherSpecInvalidError
 
 """
+
 import typing as ty
 
 import multiaddr.exceptions  # type: ignore[import]