RELEASE.md - describe how to publish to a remote IPFS server

RELEASE.md

@@ -1,46 +1,37 @@
-Since releasing new versions is currently a somewhat complicated task, the current procedure
-(17.02.2020) will be outlined in this document.
 
-All of this has only been tested on Debian 11 (Linux).
+# Release
 
-# Prerequirements
+The release process uses `flit` to build the package, `Sphinx` to generate documentation, 
+publishes the documentation to an IPFS server (obtaining an IPFS hash), and then links
+the IPFS hash (which varies based on content) to a static IPNS name.
 
-## Building and updating the project
+The IPNS name requires a private key, which is controlled by the project owners and not
+available to the public.
 
-### The `flit` project manager
+All steps can be completed up through but not including linking the IPFS hash to IPNS.
 
-APT line: `sudo apt install python3-pip && sudo pip3 install flit`  
-DNF line: `sudo dnf install python3-flit`
 
-*Note*: Version `2.0+` of `flit` is required!
+## Pre-Requisites
 
-## Building the documentation
+* On Debian
+* Python 3.8+ (or typings will be incomplete)
 
-### Sphinx & the `recommonmark` preprocessor
 
-Sphinx is the standard documentation framework for Python. Recommonmark is an extension that allows
-Sphinx to process Markdown documentation as if it where reStructuredText.
+## One-Time Setup
 
-<!-- APT line: `sudo apt install python3-sphinx python3-recommonmark`  -->
-<!--DNF line: `sudo dnf install python3-sphinx python3-recommonmark`-->
+Install the release tools into your virtual environment:
 
-At least Sphinx 3.0 with the `sphinx_autodoc_typehints` and reCommonMark 0.5 plugins is required,
-so install them using PIP:
+    $ pip install -r tools/release/requirements.txt
 
-`pip3 install Sphinx~=3.0 sphinx_autodoc_typehints recommonmark~=0.5.0`
+Source: [tools/release/requirements.txt](tools/release/requirements.txt)
 
-For best results Sphinx should be run with Python 3.8+ or typings will be incomplete.
-
-## Hosting Documentation
-
-**Both of the following need to be on the device that will *host the documentation*, not the one
-that will build it**:
 
 ### The Go IPFS daemon
 
 Yes, we use IPFS to host our documentation. In case you haven't already you can download it here:
 https://ipfs.io/docs/install/
 
+
 ### A dedicated IPNS key for publishing
 
 For publishing the documentation an IPNS key used only for this task should be
@@ -48,29 +39,53 @@ generated if there is no such key already:
 
 `ipfs key gen --type ed25519 ipfs-http-client`
 
-This key will need to be copied to all other system if the documentation is to
-be published on these as well.
+This key will need to be copied to all other servers hosting the IPNS link.
+Without the private key, other servers can host the IPFS files, but not the IPNS link.
 
 At the time of writing the officially used key is: *12D3KooWEqnTdgqHnkkwarSrJjeMP2ZJiADWLYADaNvUb6SQNyPF*
 
 
-# Steps when releasing a new version
+# Steps
 
 ## Update the source code
 
- 1. Make a GIT commit incrementing the version number in `ipfshttpclient/version.py` and completing the currently open `CHANGELOG.md` entry:  
-    `git commit -m "Release version 0.X.Y" ipfshttpclient/version.py CHANGELOG.md`)
- 2. Tag the GIT commit with the version number using an annotated and signed tag:  
+ 1. Make a GIT commit
+    * Incrementing the version number in `ipfshttpclient/version.py`
+    * Completing the currently open `CHANGELOG.md` entry
+
+    `git commit -m "Release version 0.X.Y" ipfshttpclient/version.py CHANGELOG.md`
+
+ 2. After the change is merged into master, pull master 
+
+ 3. Tag the GIT commit with the version number using an annotated and signed tag:
+
     `git tag --sign -m "Release version 0.X.Y" 0.X.Y`
- 3. Push the new version
+
+ 4. Push the new tag
+
 
 ## Upload the new version to PyPI
 
-Run: `flit build && flit publish`
+Run:
+
+    $ flit build && flit publish
 
 ## Re-generate and publish the documentation
 
-Run: `docs/publish.py ipfs-http-client` (were `ipfs-http-client` is the IPNS key ID)
+Run:
+
+    $ python docs/publish.py ipns-key-id
 
 The command will also print a commandline that may be used to mirror the generated
 documentation on systems other then the current one.
+
+If you don't have the IPNS private key, you can still exercise the documentation 
+generation and publish process:
+
+    $ python docs/publish.py
+
+If you are publishing to an IPFS server that is remote, and protected by an HTTP reverse proxy
+with TLS and basic authentication, run this instead:
+
+    $ IPFS_API_MULTI_ADDR=/dns/yourserver.tld/tcp/5001/https IPFS_API_USERNAME=basicauthuser IPFS_API_PASSWORD=basicauthpassword python publish.py ipns-key-id
+

docs/conf.py

@@ -371,6 +371,7 @@ napoleon_custom_sections = [
 
 import sphinx.ext.autodoc
 
+
 class ClientClassDocumenterBase(sphinx.ext.autodoc.ClassDocumenter):
 	directivetype = "class"
 
@@ -398,10 +399,12 @@ class ClientClassDocumenterBase(sphinx.ext.autodoc.ClassDocumenter):
 		these classes."""
 		return "({0})".format(self.args) if self.args is not None else ""
 
+
 class ClientClassDocumenter(ClientClassDocumenterBase):
 	objtype = "clientclass"
 	priority = -100
 
+
 class ClientSubClassDocumenter(ClientClassDocumenterBase):
 	objtype = "clientsubclass"
 	priority = 100
@@ -409,6 +412,7 @@ class ClientSubClassDocumenter(ClientClassDocumenterBase):
 
 import sphinx.util.inspect
 
+
 def section_property_attrgetter(object, name, default=None):
 	try:
 		prop = sphinx.util.inspect.safe_getattr(object, name)
@@ -427,6 +431,7 @@ def section_property_attrgetter(object, name, default=None):
 	# Nothing found: Return default
 	return default
 
+
 # app setup hook for reCommonMark's AutoStructify and our own extension
 def setup(app):
 	# Import the CID library so that its types will be included in the

tools/release/requirements.txt

@@ -0,0 +1,5 @@
+flit>=3.0
+Sphinx~=3.0
+sphinx_autodoc_typehints
+recommonmark~=0.5.0
+