Refactor: Adapt the API to the documentation

6 files changed, 61 insertions, 131 deletions

diff --git a/docs/src/api/go/example.md b/docs/src/api/go/example.md
index e7b0d36..0ed7d02 100644
--- a/docs/src/api/go/example.md
+++ b/docs/src/api/go/example.md
@@ -1,63 +1,13 @@
-# Example with Comments
-
+# Example with comments
+The following is an example [in the repository](https://github.com/jwijenbergh/eduvpn-common/blob/main/cmd/cli/main.go). It is a command line client with the following flags
+```
+-get-institute string
+  	The url of an institute to connect to
+-get-secure string
+  	Gets secure internet servers.
+-get-secure-all string
+  	Gets certificates for all secure internet servers. It stores them in ./certs. Provide an URL for the home server e.g. nl.eduvpn.org.
+```
 ```go
-
-// Bring the library into scope with the eduvpn prefix
-import eduvpn "github.com/jwijenbergh/eduvpn-common"
-
-// Callbacks
-
-func stateCallback(state *eduvpn.VPNState, oldState string, newState string, data string) {
-
-	// OAuth is started, open the browser with the authorization URL
-	if newState == "OAuth_Started" {
-		openBrowser(data)
-	}
-	
-	// Multiple profiles are found, we need to send a profile ID back using state.SetProfileID
-	if newState == "Ask_Profile" {
-		selectAndSendProfile(state, data)
-	}
-}
-
-func main() {
-	// Create the VPNState
-	state := &eduvpn.VPNState{}
-	
-	// Register the state
-	// We use linux so the client ID will be org.eduvpn.app.linux
-	// We want to store the config files in configs
-	// We wrap the callback with the state argument
-	// And enable debugging
-	registerErr := state.Register("org.eduvpn.app.linux", "configs", func(old string, new string, data string) {
-		stateCallback(state, old, new, data)
-	}, true)
-	
-	if registErr != nil {
-		// handle the error of not being able to register
-	}
-	
-	// Cleanup the library at the end
-	defer state.Deregister()
-	
-	// Connect to an example server without forcing TCP
-	config, configType, configErr := state.GetConnectConfig("eduvpn.example.com", false)
-	
-	if configErr != nil {
-		// handle the error of not being able to get a config
-	}
-	
-	if configType == "wireguard" {
-		// Connect using wireguard with the config
-	} else {
-	    // Connect using OpenVPN with the config
-	}
-	
-	// We are connected
-	setConnectErr := state.SetConnected()
-	
-	if setConnectErr != nil {
-		// handle the error of not being able to call set connected
-	}
-}
+{{#include ../../../../cmd/cli/main.go}}
 ```
diff --git a/docs/src/api/go/functions.md b/docs/src/api/go/functions.md
index c647787..381f5be 100644
--- a/docs/src/api/go/functions.md
+++ b/docs/src/api/go/functions.md
@@ -26,9 +26,10 @@ Returns a string of JSON data with the servers/organizations and an `error`, nil
 ## OpenVPN/Wireguard config
 See [Overview](../overview/getconfig.html)
 ```go
-func GetConnectConfig(url string, forceTCP bool) (string, string, error)
+func GetConfigInstituteAccess(url string, forceTCP bool) (string, string, error)
+func GetConfigSecureInternet(url string, forceTCP bool) (string, string, error)
 ```
-- `url`: The url of the server to get a connect config for
+- `url`: The URL of the Institute Access or Secure Internet server to get a connect config for
 - `forceTCP`: Whether or not we want to force enable TCP
 
 Returns:
@@ -36,6 +37,12 @@ Returns:
 - A `string`, `openvpn` or `wireguard` indicating if it is an OpenVPN or Wireguard config
 - An `error` (can be nil)
 
+### Cancelling OAuth
+```go
+func CancelOAuth() error
+```
+Returns an `error`, can be nil indicating no error
+
 ### Setting a profile ID
 ```go
 func SetProfileID(profileID string) error
diff --git a/docs/src/api/overview/README.md b/docs/src/api/overview/README.md
index d233b0c..8af056a 100644
--- a/docs/src/api/overview/README.md
+++ b/docs/src/api/overview/README.md
@@ -1,4 +1,4 @@
-# API Overview
+# API overview
 
 This section defines the API in high-level, we explain what functions there are, what their use is and what a typical flow is for creating an eduVPN client with this library. The language specific documentation will be given in separate sections.
 
diff --git a/docs/src/api/overview/getconfig.md b/docs/src/api/overview/getconfig.md
index 70bcb39..ca35835 100644
--- a/docs/src/api/overview/getconfig.md
+++ b/docs/src/api/overview/getconfig.md
@@ -1,6 +1,6 @@
 # Getting an OpenVPN/Wireguard config
 ## Summary
-name: `Get Connect Config`
+name: `Get Config Institute Access` and `Get Config Secure Internet`
 
 | Arguments | Description                             | type     |
 | --------- | --------------------------------------  | -------- |
@@ -13,9 +13,10 @@ Used to obtain the OpenVPN/Wireguard config
 
 ## Detailed information
 
-To get a configuration that is used to actually establish a tunnel with the VPN server, we have the Get Connect Config (the exact name depends on the language you're using) function in the library. This function has two parameters *URL* and *Force TCP*.
+To get a configuration that is used to actually establish a tunnel with the VPN server, we have the Get Config function for Institute Access and Secure Internet (the exact name depends on the language you're using) function in the library. This function has two parameters *URL* and *Force TCP*.
 
-*URL* is the base url of the server to connect to e.g. `nl.eduvpn.org`. Note that this function does not need any further input whether or not we want to connect for institute access or secure internet. This is handled in the library by checking the discovery list. If it does not find the server in the discovery list, it assumes it wants to connect as an institute server.
+*URL* is the base url of the server to connect to
+e.g. `nl.eduvpn.org`. Use the correct function to indicate if it is an Institute Access server or a Secure Internet server. A user configured server is often an Institute Access server.
 
 The *Force TCP* flag is a boolean that indicates whether or not we want to use TCP to connect over the VPN. This flag is useful if the user has enabled e.g. a setting that forces the use of TCP, which is only supported by OpenVPN. If the Force TCP flag is set to true but the server only supports Wireguard then an error is returned and the config will be empty.
 
@@ -33,6 +34,8 @@ The format of the authorization URL is e.g. this:
 
 `https://eduvpn.example.com/vpn-user-portal/oauth/authorize?client_id=org.eduvpn.app.linux&code_challenge=DsmGyWFBkvDXiIO33Fs40Z0fn4pxtzDCW2jKvAMptBg&code_challenge_method=S256&redirect_uri=http%3A%2F%2F127.0.0.1%3A8000%2Fcallback&response_type=code&scope=config&state=vha2Krx-HpOyvFkWsWYmey0jrHQ6bnb06PQ6zBXX_bg`
 
+This callback can be cancelled by using a `Cancel OAuth` function.
+
 ### Callback: Selecting a profile
 
 Another aspect that needs to be taken into account is the fact that there can be multiple profiles that a client can connect to. When the function gets called for obtaining an OpenVPN/Wireguard configuration, it asks the client which profile it wants to connect to using the callback that gets triggered on the Ask Profile state. The data is the list of profiles in JSON format, e.g.
diff --git a/docs/src/api/python/example.md b/docs/src/api/python/example.md
index 7c0997f..f371b68 100644
--- a/docs/src/api/python/example.md
+++ b/docs/src/api/python/example.md
@@ -1,48 +1,7 @@
-# Example with Comments
+# Example with comments
 
-```python
-import eduvpncommon.main as eduvpn
-
-# Callbacks
-@_eduvpn.event.on("OAuth_Started", eduvpn.StateType.Enter)
-def oauth_initialized(url):
-	# Open the webbrowser with the url
-    webbrowser.open(url)
-
-
-@_eduvpn.event.on("Ask_Profile", eduvpn.StateType.Enter)
-def ask_profile(profiles):
-	# Set a profile
-    _eduvpn.set_profile("example")
-	
-# Register the state
-# We use linux so the client ID will be org.eduvpn.app.linux
-# We want to store the config files in configs
-# And enable debugging
-_eduvpn = eduvpn.EduVPN("org.eduvpn.app.linux", "configs")
-register_err = _eduvpn.register(debug=True)
-
-if register_err:
-	# Handle error
+This is an example that can also be found [in the repository](https://github.com/jwijenbergh/eduvpn-common/blob/main/wrappers/python/main.py). It gets a config from an Institute Access server with support for multiple profiles.
 
-# Connect to eduvpn.example.com
-config, config_type, config_err = _eduvpn.get_connect_config("eduvpn.example.com", False)
-
-if config_err:
-	# Handle error
-	
-if config_type == "wireguard":
-	# Connect using wireguard with the config
-elif config_type == "openvpn":
-    # Connect using OpenVPN with the config
-else:
-	# Handle error
-
-# Set connected
-set_connect_err = _eduvpn.set_connected()
-if set_connect_err:
-	# Handle error
-
-# Handle cleanup
-_eduvpn.deregister()
+```python
+{{#include ../../../../wrappers/python/main.py}}
 ```
diff --git a/docs/src/api/python/functions.md b/docs/src/api/python/functions.md
index ebfb774..2a348cd 100644
--- a/docs/src/api/python/functions.md
+++ b/docs/src/api/python/functions.md
@@ -12,59 +12,70 @@ def __init__(self, name: str, directory: str)
 ## Registering
 See [Overview](../overview/registering.html)
 ```python
-def register(self, debug=False: bool) -> Optional[str]
+def register(self, debug: bool = False) -> None
 ```
-- `debug`: Whether or not we want to enable debugging
+- `debug`: Whether or not we want to enable debugging, default: `False`
 
-Returns an optional `string` for the error message
+Returns nothing. Raises an exception in case of an error.
 
 ## Discovery
 See [Overview](../overview/discovery.html)
 ```python
-def get_disco_servers(self) -> (Optional[str], Optional[str])
+def get_disco_servers(self) -> str
 ```
 ```python
-def get_disco_organizations(self) -> (Optional[str], Optional[str])
+def get_disco_organizations(self) -> str
 ```
 
-Returns an optional `string` of JSON data with the servers/organizations and an optional error message
+Returns a `string` of JSON data with the servers/organizations. Raises an exception in case of an error.
 
 ## OpenVPN/Wireguard config
 See [Overview](../overview/getconfig.html)
 ```python
-def get_connect_config(self, url: str, forceTCP: bool) -> (Optional[str], Optional[str], Optional[str])
+def get_config_institute_access(self, url: str, forceTCP: bool = False) -> Tuple[str, str]
 ```
-- `url`: The url of the server to get a connect config for
-- `forceTCP`: Whether or not we want to force enable TCP
+```python
+def get_config_secure_internet(self, url: str, forceTCP: bool = False) -> Tuple[str, str]
+```
+- `url`: The url of the Secure Internet or Institute Access server to get a connect config for
+- `forceTCP`: Whether or not we want to force enable TCP, default: `False`
 
 Returns:
-- An optional `string` of the OpenVPN/Wireguard config
-- An optional `string`, `openvpn` or `wireguard` indicating if it is an OpenVPN or Wireguard config
-- An optional error message `string`
+- A `string` of the OpenVPN/Wireguard config
+- An `string`, `openvpn` or `wireguard` indicating if it is an OpenVPN or Wireguard config
+
+Raises an exception in case of an error.
+
+### Cancelling OAuth
+```python
+def cancel_oauth(self) -> None
+```
+
+Returns nothing. Raises an exception in case of an error.
 
 ### Setting a profile ID
 ```python
-def set_profile(self, profile_id: str) -> Optional[str]
+def set_profile(self, profile_id: str) -> None
 ```
 - `profile_id`: The profile ID to connect to
 
-Returns an optional `string`, which is the error message
+Returns nothing. Raises an exception in case of an errorr.
 
 ## Connecting/Disconnecting
 See [Overview](../overview/connecting.html)
 ```python
-def set_connected(self) -> Optional[str]
+def set_connected(self) -> None
 ```
 ```python
-def set_disconnected(self) -> Optional[str]
+def set_disconnected(self) -> None
 ```
 
-Returns an optional `string`, which is the error message
+Returns an nothing. Raises an exception in case of an error.
 
 ## Deregister
 See [Overview](../overview/deregistering.html)
 ```python
-def deregister() -> Optional[str]
+def deregister() -> None
 ```
 
-Returns an optional `string`, which is the error message
+Returns nothing. Raises an exception in case of an error.