Improve many things about the documentation

.travis.yml

@@ -40,9 +40,9 @@ matrix:
 
 env:
   global:
-    - IPFS_VERSION=0.4.18
-    - IPFS_SHA512_LINUX=ef5b44a0aaed604890c83322ca02228061204085b87b20dd173edfe6b6631fc7a54724d2e00202488c86886992a0d409f43e09f022cdf8b1138f8419cf7614b0
-    - IPFS_SHA512_DARWIN=60cfa3920ffb9e88d06601e727376c536fc8d31f392a54a4c6c188a87449b3627e125870865f0f5eedad6a70699142fde8761166a7921aa8e588e341b7b653c9
+    - IPFS_VERSION=0.4.19
+    - IPFS_SHA512_LINUX=66d930bef0196c70f25cb207c00da6e36f6c2c17ff0e785f45d360e710502c233aeeeaaa5ee0bfc984919d42225c74c6474e5e5ce5c8cd6993580903fa8ec0c4
+    - IPFS_SHA512_DARWIN=4453499e83f9a980c6dd423d55ae6893d48a16c3bebaba0bd8ac6961e4b75d7e20ac7aa125a3d88baac3233b3536a246144b39ff3a91ec8ad6a61482292369f5
 
 
 # Ensure go-IPFS is available for testing

docs/conf.py

@@ -64,7 +64,7 @@
 
 # General information about the project.
 project = 'Python IPFS HTTP Client'
-copyright = '2016, py-ipfs-http-client team'
+copyright = '2019, py-ipfs-http-client team'
 author = 'py-ipfs-http-client team'
 
 # The version info for the project you're documenting, acts as replacement for
@@ -313,7 +313,8 @@
 
 # External documentation link mapping
 intersphinx_mapping = {
-	'python': ('https://docs.python.org/3', None)
+	'python': ('https://docs.python.org/3', None),
+	'cid': ('https://py-cid.readthedocs.io/en/master/', None)
 }
 
 # -- Napoleon settings ----------------------------------------------------

docs/http_client_ref.md

@@ -11,20 +11,53 @@ All commands are accessed through the ``ipfshttpclient.Client`` class.
 ```
 
 
+### Utility Functions
 
-### The HTTP Client
+```eval_rst
+.. data:: ipfshttpclient.DEFAULT_HOST
+
+    The default hostname that the client library will attempt to connect to.
+    This may be overwritten on a per-client-instance basis using the ``host``
+    parameter of the :func:`~ipfshttpclient.connect` function.
+
+.. data:: ipfshttpclient.DEFAULT_PORT
+
+    The default port number that the client library will attempt to connect to.
+    This may be overwritten on a per-client-instance basis using the ``port``
+    parameter of the :func:`~ipfshttpclient.connect` function.
+
+.. data:: ipfshttpclient.DEFAULT_BASE
+
+    The default HTTP URL prefix (or “base”) that the client library will use.
+    This may be overwritten on a per-client-instance basis using the ``base``
+    parameter of the :func:`~ipfshttpclient.connect` function.
+
+.. autofunction:: ipfshttpclient.connect(host=DEFAULT_HOST, port=DEFAULT_PORT, base=DEFAULT_BASE)
 
-All methods accept the following parameters in their ``kwargs``:
+.. autofunction:: ipfshttpclient.assert_version
+
+```
+
+### The API Client
 
- * **opts** (*dict*) – A dictionary of custom parameters to be sent with the
-                       HTTP request
+All methods accept the following parameters in their `kwargs`:
+
+ * **opts** (*dict*) – A mapping of custom IPFS API parameters to be sent along
+                       with the regular parameters generated by the client
+                       library
+    * Values specified here will always override their respective counterparts
+      of the client library itself.
+ * **stream** (*bool*) – Return results incrementally as they arrive?
+    * Each method called with `stream=True` will return a generator instead
+      of the documented value. If the return type is of type `list` then each
+      item of the given list will be yielded separately; if it is of type
+      `bytes` then arbitrary bags of bytes will be yielded that together form
+      a stream; finally, if it is of type `dict` then the single dictonary item
+      will be yielded once.
  * **timeout** (**float**) – The number of seconds to wait of a daemon reply
                              before giving up
 
 ```eval_rst
-.. autofunction:: ipfshttpclient.connect
-
-.. autofunction:: ipfshttpclient.assert_version
 
 .. autoclientclass:: ipfshttpclient.Client
 	:members:

ipfshttpclient/client/__init__.py

@@ -49,11 +49,11 @@ def assert_version(version, minimum=VERSION_MINIMUM, maximum=VERSION_MAXIMUM):
 	Parameters
 	----------
 	version : str
-		The version of an IPFS daemon.
+		The actual version of an IPFS daemon
 	minimum : str
-		The minimal IPFS version to allow.
+		The minimal IPFS daemon version to allowed
 	maximum : str
-		The maximum IPFS version to allow.
+		The maximum IPFS daemon version to allowed
 	"""
 	# Convert version strings to integer tuples
 	version = list(map(int, version.split('-', 1)[0].split('.')))
@@ -84,7 +84,7 @@ def connect(host=DEFAULT_HOST, port=DEFAULT_PORT, base=DEFAULT_BASE,
 
 	Returns
 	-------
-		~ipfshttpclient.Client
+		:class:`~ipfshttpclient.Client`
 	"""
 	# Create client instance
 	client = Client(host, port, base, chunk_size, **defaults)
@@ -96,6 +96,16 @@ def connect(host=DEFAULT_HOST, port=DEFAULT_PORT, base=DEFAULT_BASE,
 
 
 class Client(files.Base, miscellaneous.Base):
+	"""The main IPFS HTTP client class
+
+	Allows access to an IPFS daemon instance using its HTTP API by exposing an
+	`IPFS Interface Core <https://github.com/ipfs/interface-ipfs-core/tree/master/SPEC>`__
+	compatible set of methods.
+
+	It is possible to instantiate this class directly, using the same parameters
+	as :func:`connect`, to prevent the client from checking for an active and
+	compatible version of the daemon.
+	"""
 	bitswap   = base.SectionProperty(bitswap.Section)
 	block     = base.SectionProperty(block.Section)
 	bootstrap = base.SectionProperty(bootstrap.Section)
@@ -134,7 +144,8 @@ def add_bytes(self, data, **kwargs):
 
 		Returns
 		-------
-			str : Hash of the added IPFS object
+			str
+				Hash of the added IPFS object
 		"""
 		body, headers = multipart.stream_bytes(data, self.chunk_size)
 		return self._client.request('/add', decoder='json',
@@ -159,7 +170,8 @@ def add_str(self, string, **kwargs):
 
 		Returns
 		-------
-			str : Hash of the added IPFS object
+			str
+				Hash of the added IPFS object
 		"""
 		body, headers = multipart.stream_text(string, self.chunk_size)
 		return self._client.request('/add', decoder='json',
@@ -180,7 +192,8 @@ def add_json(self, json_obj, **kwargs):
 
 		Returns
 		-------
-			str : Hash of the added IPFS object
+			str
+				Hash of the added IPFS object
 		"""
 		return self.add_bytes(encoding.Json().encode(json_obj), **kwargs)
 
@@ -196,11 +209,12 @@ def get_json(self, cid, **kwargs):
 
 		Parameters
 		----------
-		cid : Union[str, cid.BaseCID]
+		cid : Union[str, cid.CIDv0, cid.CIDv1]
 		   CID of the IPFS object to load
 
 		Returns
 		-------
-			object : Deserialized IPFS JSON object value
+			object
+				Deserialized IPFS JSON object value
 		"""
 		return self.cat(cid, decoder='json', **kwargs)

ipfshttpclient/client/bitswap.py

@@ -25,7 +25,11 @@ def wantlist(self, peer=None, **kwargs):
 
 		Returns
 		-------
-			dict : List of wanted blocks
+			dict
+
+		+------+----------------------------------------------------+
+		| Keys | List of blocks the connected daemon is looking for |
+		+------+----------------------------------------------------+
 		"""
 		args = (peer,)
 		return self._client.request('/bitswap/wantlist', args, decoder='json', **kwargs)
@@ -57,6 +61,7 @@ def stat(self, **kwargs):
 
 		Returns
 		-------
-			dict : Statistics, peers and wanted blocks
+			dict
+				Statistics, peers and wanted blocks
 		"""
 		return self._client.request('/bitswap/stat', decoder='json', **kwargs)

ipfshttpclient/client/block.py

@@ -21,12 +21,13 @@ def get(self, cid, **kwargs):
 
 		Parameters
 		----------
-		cid : Union[str, cid.BaseCID]
-			The base58 CID of an existing block to get
+		cid : Union[str, cid.CIDv0, cid.CIDv1]
+			The CID of an existing block to get
 
 		Returns
 		-------
-			bytes : Value of the requested block
+			bytes
+				Contents of the requested block
 		"""
 		args = (str(cid),)
 		return self._client.request('/block/get', args, **kwargs)
@@ -49,9 +50,10 @@ def put(self, file, **kwargs):
 
 		Returns
 		-------
-			dict : Information about the new block
-
-				   See :meth:`~ipfshttpclient.Client.block.stat`
+			dict
+				Information about the new block
+
+				See :meth:`~ipfshttpclient.Client.block.stat`
 		"""
 		body, headers = multipart.stream_files(file, self.chunk_size)
 		return self._client.request('/block/put', decoder='json', data=body,
@@ -70,12 +72,13 @@ def stat(self, cid, **kwargs):
 
 		Parameters
 		----------
-		cid : Union[str, cid.BaseCID]
-			The base58 CID of an existing block to stat
+		cid : Union[str, cid.CIDv0, cid.CIDv1]
+			The CID of an existing block to stat
 
 		Returns
 		-------
-			dict : Information about the requested block
+			dict
+				Information about the requested block
 		"""
 		args = (str(cid),)
 		return self._client.request('/block/stat', args, decoder='json', **kwargs)

ipfshttpclient/client/bootstrap.py

@@ -37,11 +37,16 @@ def list(self, **kwargs):
 				'/ip4/104.236.176.52/tcp/4001/ipfs/QmSoLnSGccFuZQJzRa … ca9z',
 				'/ip4/104.236.179.241/tcp/4001/ipfs/QmSoLPppuBtQSGwKD … KrGM',
 				…
-				'/ip4/178.62.61.185/tcp/4001/ipfs/QmSoLMeWqB7YGVLJN3p … QBU3']}
+				'/ip4/178.62.61.185/tcp/4001/ipfs/QmSoLMeWqB7YGVLJN3p … QBU3'
+			]}
 
 		Returns
 		-------
-			dict : List of known bootstrap peers
+			dict
+
+		+-------+-------------------------------+
+		| Peers | List of known bootstrap peers |
+		+-------+-------------------------------+
 		"""
 		return self._client.request('/bootstrap', decoder='json', **kwargs)
 

ipfshttpclient/client/config.py

@@ -10,11 +10,6 @@ def get(self, **kwargs):
 		#TODO: Support the optional `key` parameter
 		"""Returns the current used server configuration.
 
-		.. warning::
-
-			The configuration file contains private key data that must be
-			handled with care.
-
 		.. code-block:: python
 
 			>>> config = client.config.get()
@@ -27,30 +22,31 @@ def get(self, **kwargs):
 
 		Returns
 		-------
-			dict : The entire IPFS daemon configuration
+			dict
+				The entire IPFS daemon configuration
 		"""
 		return self._client.request('/config/show', decoder='json', **kwargs)
 
 
 	@base.returns_single_item
 	def replace(self, config, **kwargs):
-		"""Replaces the existing config with a user-defined config.
+		"""Replaces the existing configuration with a new configuration tree.
 
 		Make sure to back up the config file first if neccessary, as this
-		operation can't be undone.
+		operation can not be undone.
 		"""
 		return self._client.request('/config/replace', (config,), decoder='json', **kwargs)
 
 
 	@base.returns_single_item
 	def set(self, key, value=None, **kwargs):
-		"""Add or replace a configuration value.
+		"""Add or replace a single configuration value.
 
 		.. code-block:: python
 
-			>>> client.config("Addresses.Gateway")
+			>>> client.config.set("Addresses.Gateway")
 			{'Key': 'Addresses.Gateway', 'Value': '/ip4/127.0.0.1/tcp/8080'}
-			>>> client.config("Addresses.Gateway", "/ip4/127.0.0.1/tcp/8081")
+			>>> client.config.set("Addresses.Gateway", "/ip4/127.0.0.1/tcp/8081")
 			{'Key': 'Addresses.Gateway', 'Value': '/ip4/127.0.0.1/tcp/8081'}
 
 		Parameters
@@ -62,7 +58,13 @@ def set(self, key, value=None, **kwargs):
 
 		Returns
 		-------
-			dict : Requested/updated key and its (new) value
+			dict
+
+		+-------+---------------------------------------------+
+		| Key   | The requested configuration key             |
+		+-------+---------------------------------------------+
+		| Value | The new value of the this configuration key |
+		+-------+---------------------------------------------+
 		"""
 		args = (key, value)
 		return self._client.request('/config', args, decoder='json', **kwargs)