docs: add basic docs for oauth2 setup, import data from farmOS

docs/narr/auth.rst

@@ -36,7 +36,13 @@ browse farmOS data within the WuttaFarm views.
 
    If you login to WuttaFarm directly with username/password, then
    your user session will not have a farmOS access token and so the
-   farmOS data views in WuttaFarm will not work.
+   farmOS data views in WuttaFarm will not work (i.e. anything under
+   the **farmOS** menu).
+
+   (However this does not affect the "native" data views for
+   WuttaFarm.  Users can see data which was already imported from
+   farmOS without an access token - if they have appropriate
+   permissions in WuttaFarm.)
 
 On the login page, click the "Login via farmOS / OAuth2" button.  This
 will initiate the OAuth2 workflow, at which point you may be asked to

docs/narr/features.rst

@@ -14,6 +14,10 @@ Here is the list of features currently supported:
    * performance isn't bad, but data is not very "complete"
    * more data could be fetched, but not sure this is the best way..?
 
+* import some data from farmOS
+   * limited data is imported from farmOS API into native app tables
+   * this data is exposed in views, similar to direct farmOS views (above)
+
 
 Screenshots
 -----------

docs/narr/install.rst

@@ -60,3 +60,93 @@ are encouraged to enable it anyway.
 When the installer completes it will output a command you can then use
 to run the web app.  Do that and you can then view the app in a
 browser at http://localhost:9080
+
+
+OAuth2 Setup
+------------
+
+At this point the web app should be ready for OAuth2 login; however
+the OAuth2 provider in farmOS needs some more config before it will
+work.
+
+WuttaFarm uses the default ``farm`` consumer, so the only thing you
+should have to do here is edit that to add your redirect URL.  This
+will vary based on your WuttaFarm site name, e.g.
+
+.. code-block:: none
+
+   https://wuttafarm.example.com/farmos/oauth/callback
+
+With that in place you should be able to login via OAuth2; see also
+:doc:`/narr/auth`.
+
+However while you're there, you should also do some setup for the sake
+of the farmOS → WuttaFarm data import.  This import will also use the
+farmOS API and therefore also needs an oauth2 access token; however it
+uses the Client Credentials workflow instead of the Authorization Code
+workflow.  Therefore you must create a new *user* and a new OAuth2
+*consumer* for it.
+
+First add a new user in farmOS, named ``wuttafarm``.  It should
+probably be given the Manager role, since WuttaFarm will eventually
+also support "exporting" data back to farmOS.
+
+Then add a new OAuth2 consumer (aka. client) with these attributes:
+
+* **Label:** WuttaFarm
+* **Client ID:** wuttafarm
+* **New Secret:** (put something in here, to be used as client secret)
+* **Grant Types:** Client Credentials, Refresh Token (maybe more?)
+* **User:** wuttafarm
+* **3rd Party?** yes
+* **Confidential?** yes
+* **Access Token Expiration Time:** maybe set to 3600? or maybe 300
+  default is okay?
+* **Allowed Origins:** put your oauth callback URL here (same as for
+  default ``farm`` consumer)
+
+WuttaFarm also needs to know the client secret for sake of running the
+import; so add this to your ``app/wutta.conf`` file.  Of course
+replace the value with whatever client secret you gave the new
+consumer:
+
+.. code-block:: ini
+
+   [farmos.oauth2]
+   importing.client_secret = you_cant_guess_me
+
+
+Import Data from farmOS
+-----------------------
+
+You must have done all the OAuth2 setup (previous section) before the
+import will work.
+
+But now that you did all that, importing should be quick and easy.
+
+The very first import will be limited and "special" to account for any
+users which were already created in WuttaFarm.  This command will
+ensure WuttaFarm gets *all* user accounts and each is appropriately
+mapped to the farmOS account:
+
+.. code-block:: sh
+
+   ./venv/bin/wuttafarm --runas farmos import-farmos User --key username
+
+Note also the ``--runas farmos`` arg which helps the WuttaFarm data
+versioning know "who" is responsible for the changes.  We use a
+dedicated ``farmos`` user account in WuttaFarm, to represent the
+farmOS system as a whole.
+
+From now on you can run the "full" import normally:
+
+.. code-block:: sh
+
+   ./venv/bin/wuttafarm --runas farmos import-farmos
+
+And it can sometimes be helpful to "double-check" in order to make
+sure all data is fully synced:
+
+.. code-block:: sh
+
+   ./venv/bin/wuttafarm --runas farmos import-farmos --delete --dry-run -W