Docs: some doc fixes, refactorings and ext clarification (#1789)

* Docs: some doc fixes, refactorings and ext clarification * Further fixes and recovering search * Only main heading has one # so that navigation works * remove about * docs: update TOC * Adjust release-notes script * remove authors plugin properly * corrections & simplifications * cli_text.py updated * architecture.md edited * extensions and some small fixes * docs: update TOC Co-authored-by: k9ert <[email protected]> Co-authored-by: moneymanolis <[email protected]>
cryptoadvance · Aug 22, 2022 · e43a6bf · e43a6bf
1 parent 786b090
commit e43a6bf
Show file tree

Hide file tree

Showing 20 changed files with 292 additions and 239 deletions.
diff --git a/docs/about.md b/docs/about.md
@@ -0,0 +1,3 @@
+
+
+{{ git_site_authors }}
diff --git a/docs/architecture.md b/docs/architecture.md
@@ -1,21 +1,21 @@
-# Architectural Notes
+# Architectural notes
 
-specter-desktop and specter-cloud are flask-applications and follow typical Model-View-Control-principles. The model-part is covered by a number of business-objects and managers who are responsible for maintaining/managing those. Currently we have these managers:
+Specter Desktop and Specter Cloud are flask applications and follow typical model-view-controller principles. The model part is covered by a number of business objects and managers who are responsible for maintaining/managing those. Currently we have these managers:
 
 ## Managers
 
-* GenericDataManager is abstracting persistence-aspects and most managers which are persisting json-data are derived from this one.
-* ConfigManager where the api-docs tells us: "The ConfigManager manages the configuration persisted in config.json. It's not supposed to have any side-effects. Setting and getting only with a lot of validation and computing while setting/getting."
-* DeviceManager where the api-docs tells us: "A DeviceManager mainly manages the persistence of a device-json-structures compliant to helper.load_jsons.py".
+* GenericDataManager is abstracting persistence aspects and most managers which are persisting json data are derived from this one.
+* The ConfigManager manages the configuration persisted in config.json. It's not supposed to have any side-effects. Setting and getting only with a lot of validation and computing while setting/getting.
+* A DeviceManager mainly manages the persistence of a device-json structure compliant to helper.load_jsons.py.
 * NodeManager manages internal and external nodes.
 * UserManager manages all stuff regarding Users.
-* Similarly the WalletManager
+* Similarly, the WalletManager manages all wallet stuff. 
 
-## Views / Blueprints
-The controller is covered by "server_endpoints". Those are split up in “blueprints”. This is a way to split the urls in sub-urls. These sub-urls are loosely related to the business-objects: `/welcome`, `/auth`, `/devices`, `/nodes`, `/price`, `/services` (should be renamed "`/plugins`"), `/settings`, `/setup`, `/wallets`.
+## Views and blueprints
+The controller part is covered by "server_endpoints". Those are split up in “blueprints”. This is a way to split the urls in sub-urls. These sub-urls are loosely related to the business-objects: `/welcome`, `/auth`, `/devices`, `/nodes`, `/price`, `/services` (should be renamed "`/plugins`"), `/settings`, `/setup`, `/wallets`.
 
 ## Views
-The views are effectively jinja2 templates which can extend from higher order ones and have placeholders which templates can then override. The `base.jinja` lays out the basic layout having a block for the `sidebar` and a `main` block (plus `head` and `scripts` ). Some blueprints (`/settings`,`/wallets`) span up a top-level-navigation. In that case, the template extend from its specific blueprint-base-template which in turn provides a block called `content` and the template decides which menu-point is active:
+The views are effectively jinja2 templates which can extend from higher order ones and have placeholders which templates can then override. The `base.jinja` lays out the basic layout having a block for the `sidebar` and a `main` block (plus `head` and `scripts` ). Some blueprints (`/settings`,`/wallets`) span up a top-level navigation. In that case, the template extends from its specific blueprint-base template which in turn provides a block called `content` and the template decides which menu point is active:
 ```
 {% extends "wallet/components/wallet_tab.jinja" %}
 {% set tab = 'receive' %}
@@ -26,6 +26,6 @@ This is also a pattern used for plugins.
 
 # Plugins
 
-The more specific a functionality became, the more awkward it felt to be integrated in the above core-Architecture. When we started to make exchange specific functionality, we wanted to protect the core-Architecture from deluting. Therefore we created a plugin-concept which allows to have the above concepts replicated in it there own self-contained standalone units.
+The more specific a functionality became, the more awkward it felt to integrate it in the core architecture. When we started to make exchange specific functionality, we wanted to protect the core architecture. Therefore, we created a plugin concept which allows to have the above concepts replicated in their own self-contained standalone units. 
 
-We try now to implement bigger chunks of functionality in plugins. Maybe even core-functionality might be placed with "core-plugins" in the future. Those are placed in `src/specterext`. But plugins can also live in there own repos, have their own release-lifecycle and be used by Specter like any other dependency as well. For more information about plugins see [Third Party Service Integrations](./services/services.md).
+We now try to implement bigger chunks of functionality in plugins. Maybe, even core functionality might be implemented in "core plugins" in the future. Internal plugins are placed in `src/specterext`. But, plugins can also live in there own repos, have their own release lifecycle and be used by Specter like any other dependency. For more information about plugins see [Third Party Service Integrations](./extensions.md) where we also discuss the nuances between plugins and extensions.
diff --git a/docs/continuous-integration.md b/docs/continuous-integration.md
@@ -11,7 +11,7 @@ Cirrus-CI:
 * supports the PR-model
 * quite easy to setup even though it's using docker
 
-# Gitlab
+## Gitlab
 
 Gitlab is a great CI/CD-platform and in the meantime it's quite easy to use it for GitHub-repositories.
 https://docs.gitlab.com/ee/ci/ci_cd_for_external_repos/github_integration.html
@@ -32,31 +32,31 @@ start_bitcoind-function:
 * adding -rpcallowip= (from a docker network) to bitcoind
 * not use localhost but the docker-network-ip-address when talking to the bitcoind
 
-# Travis-CI
+## Travis-CI
 
 We're no longer using travis-ci due to the abuse-detection-system going wild on us.
 
-# Cirrus-CI
+## Cirrus-CI
 
 [Cirrus-CI](https://cirrus-ci.org) is used by Bitcoin-Core and HWI and is a quite good replacement for travis. We're using it only for PRs so far. The [../.cirrus.yml] file defines the build. We have two task, one for pytest and one for the [cypress-tests](./cypress-testing.md).
 
-# Releasing
+## Releasing
 
-## What gets released
+### What gets released
 
 We're mostly releasing automatically. Currently the following artifacts are released:
 * specterd (daemon) is a binary for kicking off the specter-desktop service on the command-line. We have binaries for windows, Linux and macOS
 * We have an Electron-App which we're also releasing for Windows, Linux and MacOS. Unfortunately the macOS build is not yet automated
 * We release a pip-package
 * Usually some time after the release, the lncm is releasing [docker-images](https://hub.docker.com/r/lncm/specter-desktop). Very much appreciated, even though we can't guarantee for them, obviously.
 
-# How we release
+### How we release
 As we have a strict build-only-on-private-hardware build-policy, we're using GitLab private runners in order to build our releases. In order to test and develop the releasing automation, people can setup GitLab-projects which are syncing from their GitHub-forks. With such a setup it's possible to create test-releases and therefore test the whole procedure end-to-end.
 
 The automation of that kicks in if someone creates a tag which is named like "vX.Y.Z". This is specified in the gitlab-ci.yml. The release-job will only be triggered in cases of tags. One step will also check that the tag follows the convention above.
 The package upload will need a token. How to obtain the token is described in the packaging-tutorial. It's injected via GitLab-variables. ToDo: put the token on a trusted build-node.
 
-## pyinstaller system-dependent binaries
+### pyinstaller system-dependent binaries
 The [pyinstaller directory](../pyinstaller) contains scripts to create the platform-specific binaries (plus electron) to use specter-desktop as a desktop-software. Some of them are created and uploaded to [GitHub-releases](https://github.com/cryptoadvance/specter-desktop/releases) via more or less special build-agents.
 The [windows-build-agent](https://docs.gitlab.com/runner/install/windows.html) needs manual installation 
 of git, python and docker. Docker is used to build the innosetup-file.
@@ -65,7 +65,7 @@ log into the windows-machine to get docker started.
 Clearly there is an opportunity to move all of the creation of the windows-binary to wine on docker,
 similiar to the way the innosetup is running within docker.
 
-# CI/CD-dev-env setup
+## CI/CD-dev-env setup
 
 Here is a brief description on how to create a setup where the release-procedures can be tested:
 * We assume you have a fork of cryptoadvance/specter-desktop. We also assume that your GitLab-user-handle is the exact same as on GitHub.
@@ -77,11 +77,11 @@ Here is a brief description on how to create a setup where the release-procedure
 * create a tag on your GitHub-fork
 * watch the test-release unfolding, ready to hack
 
-# GitLab-runner setup (Windows)
+### GitLab-runner setup (Windows)
 
 For Windows-releasing, we're using a windows GitLab-runner. Here is a short description on how to set one up.
 
-## Prerequisites
+#### Prerequisites
 
 You need at least Windows Home 10 which is up-to-date. The most complex dependency is setting up docker.
 Docker-Desktop needs a WSL2 which is a good idea to install on windows anyway. [Here](https://www.omgubuntu.co.uk/how-to-install-wsl2-on-windows-10) is a description on how to do that.
@@ -96,7 +96,7 @@ Now open and check the "Environment-variables" and check that the following line
 
 ![](./images/continuous-integration_runner_windows_envvars.png)
 
-## Runner
+#### Runner
 
 The runner itself is easy to [setup](https://docs.gitlab.com/runner/install/windows.html). Follow the link or this very brief description:
 *  `mkdir \Gitlab-Runner`

diff --git a/docs/daemon.md b/docs/daemon.md
@@ -68,7 +68,7 @@ WantedBy=multi-user.target
 
 You can check the status of specter.service by running `systemctl status specter.service` or for debugging, you can get more information by running `sudo journalctl -fu specter.service`
 
-The commented section of the service file above refers to an optional reverse proxy setup which is covered in the [reverse_proxy.md](reverse_proxy.md) document.
+The commented section of the service file above refers to an optional reverse proxy setup which is covered in the [reverse_proxy.md](reverse-proxy.md) document.
 
 ## bitcoind as a Service
 

diff --git a/docs/elements.md b/docs/elements.md
@@ -5,10 +5,10 @@ This document is a description on how to get started with elements/liquid. We'll
 
 After that, we'll explain how to connect your Specter Desktop to that node, create wallets and receive some coins (via sideshift.ai). Signing transactions is nowhere different than in any other Hotwallet.
 
-# Elements Installation
+## Elements Installation
 The Elements's instalaation is highly dependent to your system. Choose a fitting [artifact](https://github.com/ElementsProject/elements/releases) and install them. 
 
-# Liquid Node
+## Liquid Node
 In order to validate Peg-Ins, you'll need RPC-access to your Bitcoin-Core node. I did this with a fullnode, it might also work with a pruned node (not tested, though).
 
 First, we need to create the `elements.conf` file which is located in the `datadir`. If you don't specify the datadir at startup, the standard-directory is `<homefolder>/.elements/elements.conf`. Here is an example:
@@ -40,7 +40,7 @@ A successfull startup will result in validating the blocks. Currently the blockh
 
 It took about 12 hours for a full-sync in my case on a Intel Quadcore Gen 6 3.50GHz.
 
-# Liquid Configuration in Specter
+## Liquid Configuration in Specter
 
 You're probably familiar with this part. On the upper-left, click on the `two arrows -> connect a new node -> Connect existing node`. Here is a screenshots with the values fitting to the configuration above:
 
@@ -54,7 +54,7 @@ As you can your wallets disappeared but your devices did not. The shown wallets
 
 ![](./images/elements/nodechoose.png)
 
-# Hotwallet-Creation
+## Hotwallet-Creation
 
 The process of creating a Liquid Hotwallet is very similiar to creating a Bitcoin-Core Hotwallet. First you need to create a Hotwallet-Device `Add new device -> Elements Core (hot wallet) -> Continue -> Enter Name -> Continue` (Don't forget to note the seed).
 After that, you can directly create a single key wallet: `Create single key wallet -> Enter Name -> Create Wallet`. You can download the usual Backup Pdf.
@@ -63,7 +63,7 @@ So if you now get a receive-address, you have to choose between a Confidential a
 
 ![](./images/elements/receive.png)
 
-# Fund the wallet
+## Fund the wallet
 
 There are many ways you can fund your wallet. Let's assume you have Bitcoin and want to receive LiquidBtc (LBTC). At [https://sideswap.io/peg-in-out/](https://sideswap.io/peg-in-out/) you can Peg-In some Btc as a service. At [https://sideshift.ai/](https://sideshift.ai/) you can [https://sideshift.ai/btc/liquid](swap) BTC agains LBTC (and [vice versa](https://sideshift.ai/liquid/btc)).
 
@@ -73,9 +73,9 @@ As an example, let'S choose sideshift.ai to swap some BTC to LBTC.
 
 ![](./images/elements/txs.png)
 
-## Advanced stuff: Elements Compilation
+### Advanced stuff: Elements Compilation
 
-# Elements Compilation
+## Elements Compilation
 
 Since `v1.7.0`, It's no longer needed to compile Elements yourself as Specter is now working with Elements [0.21.0](https://github.com/ElementsProject/elements/releases/tag/elements-0.21.0).
 However, maybe you want to compile it for some reason, so here is a quick guide on how to do that.

diff --git a/docs/endless-pacman.md b/docs/endless-pacman.md
@@ -1,21 +1,23 @@
+# Introduction
+
 Sometimes people have issues where they get an endless Pacman animation and the application is not coming up. If you suffer from this, here are some hints on how to deal with that.
 
-# Check The Logs
+## Check The Logs
 The logs are usually in the `.specter` subfolder of your homediretory. There, you might find a file called `specter.log` and/or specterApp.log. If you're running Specter as a binary application (in contrast to a pip installation) which most people do that `specterApp.log` is the relevant file for you. This file might contain content which gives a hint on what's wrong. If you can't find anything suspicious, feel free to create a [pastebin](https://pastebin.com/) and ask in the chat for help (with a link to the created pastebin).
 
-# USB-issues
+## USB-issues
 Sometimes some devices attached via USB are blocking the startup. We had that in the past with a Game-Controller. In one case, the USB drivers where so screwed up, that only a windows in protected mode could start Specter.
 
-# Check Port 25441
+## Check Port 25441
 Maybe there is another instance (still) running. Check that via opening your brower here: [http://localhost:25441](http://localhost:25441)
 If that's the case, the most easy solution is to reboot your computer.
 
-# Check security software
+## Check security software
 Sometimes, security software is distorting the startup.
 
 E.g. Acronis is a protective system which is known to prevent starting up of Specter on windows. Other security-software might be behaving similary. For troubleshooting purposes, switch off your protective software and try again. If that helps, you need to allow specter to be running on port 25441. Check the manual on how to achieve that manually.
 
-# Check Whether the Binary is Existing
+## Check Whether the Binary is Existing
 The first thing Specter is doing if you start up the app is downloading the correct specterd from the GitHub-release page and storing that executable in the `Homefolder/.specter/specterd-binaries` subfolder. You should find a file called `specterd`.
 If the file is there but you still get the endless Pacman, try one of the following things:
 * delete the file so it'll get redownloaded