Merge ~woutervb/snap-store-proxy-charm:SN-486 into snap-store-proxy-charm:master

[Wouter van Bommel]

Initial start of documentation

The idea is to have the charm documentation (that is published via discourse) as part of the code repository, so that it can grow with the evolution of the charm.

As far as currently known, there is now way to automate the publishing.

This documentation refers to a snap called `store-admin` which is currently under development as it is an evolution of the current snap-store-client snap. So documentation should not be made life before this snap is available, but that allows proofreading / fine tuning of what we actually publish.

[Wouter van Bommel (woutervb)]

Added a comment for reviewers

[Przemysław Suliga (suligap)]

lgtm with some typos / small fixes.

review: Approve

[Wouter van Bommel (woutervb)]

> lgtm with some typos / small fixes.

Thanks fixed all but one PostgreSQL vs PostgresSQL, did a lookup of the first one

diff --git a/Makefile b/Makefile
index c09cee6..cea8799 100644
--- a/Makefile
+++ b/Makefile
@@ -60,6 +60,8 @@ lint: $(ENV)
 	@$(ENV)/bin/black --check src tests
 	@echo Running isort
 	@$(ENV)/bin/isort --profile black --check src tests
+	@echo Running documentation lint
+	@$(ENV)/bin/pymarkdown -d MD041,MD025 scan docs
 
 .PHONY: clean
 clean: $(CHARMCRAFT)
diff --git a/README.md b/README.md
index 2a76997..0c0b870 100644
--- a/README.md
+++ b/README.md
@@ -79,3 +79,9 @@ An example bundle to do such a deployment will look like the following.
       - snap-store-proxy:db-admin
 
 With the above example it is assumed that both the `core20.snap` and the `snap-store-proxy.snap` are available in the current directory. The snaps can be downloaded using the `snap download core20` and `snap download snap-store-proxy` resp.
+
+# Documentation
+
+Documentation of the charm will be published on discourse, following the guide https://juju.is/tutorials/add-docs-to-your-charmhub-page#1-overview. Since there is no version history or any form of checking for correctness on discourse. The pages published there, will be a mirror of what is actually present in the `docs/` directory.
+
+As the markup used on discourse is commonmark, the lint make target has been adapted to validate all the files in the docs directory.
\ No newline at end of file
diff --git a/docs/contributing.md b/docs/contributing.md
new file mode 100644
index 0000000..0958697
--- /dev/null
+++ b/docs/contributing.md
@@ -0,0 +1,26 @@
+For any problems with this charm, please [report here](https://bugs.launchpad.net/snap-store-proxy-charm/+filebug)
+
+Development takes place on `Ubuntu Focal` (20.04-lts) which is also the target Ubuntu
+release for the charm. The only supported architecture for now is `AMD64`.
+
+To obtain the code use the following command:
+
+    git clone https://git.launchpad.net/snap-store-proxy-charm
+
+Tests can be run via `make test` from within the code directory.
+
+# Local deployment
+
+To deploy locally, juju and lxd are required, and tje charm and postgresql will
+be deployed to the same model.
+
+    sudo apt install make
+    sudo snap install lxd
+    sudo snap install juju --classic
+    # Be sure to disable ipv6 for now, as juju doesn't support it
+    sudo lxd init
+    juju bootstrap localhost
+
+    # Use the deploy target defined in the Makefile
+    make deploy
+    # and follow any instruction given
diff --git a/docs/install.md b/docs/install.md
new file mode 100644
index 0000000..3f6ba93
--- /dev/null
+++ b/docs/install.md
@@ -0,0 +1,68 @@
+This charm will install a snap-store-proxy on local premises. In order to do
+this, a registration bundle is required. This registration bundle can be
+obtained via the snap `store-admin`.
+
+The charm can be installed in two ways. The preferred way is to use the
+snap-store itself, which means that the machine instances on which the
+`snap-store-proxy-charm` is installed, needs to be to connect to the store.
+
+The other way is, to download the `snap-store-proxy*.snap` and the
+`core20-*.snap` and attach these as resources to the `snap-store-proxy-charm`
+during installation. After installation a resource can be updates via juju,
+by attaching a newer resource. This will be the only way to update the charm.
+
+It is not possible to switch between these 2 modes of installation.
+
+# Basic install
+
+An example juju-bundle, that can be used for installation:
+
+    applications:
+      postgresql:
+        charm: ch:postgresql
+        channel: stable
+        num_units: 1
+      snap-store-proxy:
+        charm: ch:snap-store-proxy-charm
+        num_units: 1
+    
+    relations:
+    - - postgresql:db-admin
+      - snap-store-proxy:db-admin
+
+# Resource based install
+
+When using a resource based install the core20 an snap-store-proxy snap's can
+be downloaded via the command: `snap download core20` and
+`snap download snap-store-proxy`. Once this is done the following juju bundle
+can be used for installation.
+
+    applications:
+      postgresql:
+        charm: ch:postgresql
+        channel: stable
+        num_units: 1
+      snap-store-proxy:
+        num_units: 1
+        resources:
+          snap-store-proxy: snap-store-proxy_<number>.snap
+          core: core20_<number>.snap
+    
+    relations:
+    - - postgresql:db-admin
+      - snap-store-proxy:db-admin
+
+# Configuration
+
+In both the installation examples above, the charm still needs to be
+registered. This registration has to be done via the snap `store-admin` and
+will produce a registration file. This registration file needs to be added,
+encoded using base64, to the charm option called `registration_bundle`.
+
+I this file is called `register.json` the following command can be used:
+
+    juju config snap-store-proxy \
+        registration_bundle=$(cat register.json | base64 -w 0)
+
+Obviously this can also be added to the juju deployment bundle, both methods,
+registering during installation, or after installation, are supported.
diff --git a/docs/snap-store-proxy-charm docs - index.md b/docs/snap-store-proxy-charm docs - index.md
new file mode 100644
index 0000000..ff47ce5
--- /dev/null
+++ b/docs/snap-store-proxy-charm docs - index.md
@@ -0,0 +1,29 @@
+A charm that install the snap-store-proxy snap
+
+To get started, deploy the charm in a test environment as follows:
+
+    juju deploy postgresql
+    juju deploy snap-store-proxy-charm
+    juju relate postgresql:db-admin snap-store-proxy-charm:db-admin
+    juju config snap-store-proxy-charm registration_bundle=\
+        $(cat <registration bundle> | base64)
+
+For more information on how to obtain a registration bundle [see here](https://snapcraft.io/store-admin).
+
+For more information about PostgreSQL and the relation [see this section](https://discourse.charmhub.io/t/mattermost-documentation-database-relations/3759).
+
+# Navigation
+
+| Level | Path | Navlink |
+| -- | -- | -- |
+| 1 |  | [Overview](/t/topic-title/<ID>) |
+| 1 | install | [install](/t/topic-title/<ID>) |
+| 1 | contributing | [Contributing](/t/topic-title/<ID>) |
+| 1 | upgrading | [Upgrading](/t/topic-title/<ID>) |
+
+# Redirects
+
+[details=Mapping table]
+| Path | Location |
+| -- | -- |
+[/details]
diff --git a/docs/upgrading.md b/docs/upgrading.md
new file mode 100644
index 0000000..f1ddcce
--- /dev/null
+++ b/docs/upgrading.md
@@ -0,0 +1,14 @@
+There are 2 parts of the charm can can be upgraded. The charm itself, and the
+`snap-store-proxy.snap` that is manged by the charm.
+
+If the snap is installed from the snapstore, and the instance on which it is
+installed, can reach the snapstore, it will update itself automatically.
+
+If the snap is installed as a resource, then upgrading means attaching the newer
+version of the snap as a resource. In this case, also the core20.snap needs to be
+updated manually.
+
+Upgrading the charm is done via juju, it is simply a matter of running the
+[juju command to upgrade applications](https://juju.is/docs/upgrading-applications)
+
+    juju refresh snap-store-proxy-charm
diff --git a/requirements-dev.txt b/requirements-dev.txt
index 0948d86..cdd103c 100644
--- a/requirements-dev.txt
+++ b/requirements-dev.txt
@@ -12,3 +12,4 @@ pytest-xdist
 pytest-sugar
 pytest-cov
 pytest-isort
+pymarkdownlnt
\ No newline at end of file