From 25ab43c8ba9c5dc0aaad30cc89045aabb5c95038 Mon Sep 17 00:00:00 2001 From: "Stanislav N. aka pztrn" Date: Tue, 12 Mar 2019 21:46:29 +0500 Subject: [PATCH] Some documentation fixes, related to #4. --- README.md | 22 +++++++++++---------- doc/configuration.md | 34 ++++++++++++++++----------------- doc/software_that_works_good.md | 10 ++++++++++ 3 files changed, 39 insertions(+), 27 deletions(-) create mode 100644 doc/software_that_works_good.md diff --git a/README.md b/README.md index dd74158..d7a8fbc 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ Initially this project was created for integrating Gitlab and Gitea into Matrix, Join [#opensaps:pztrn.name](https://matrix.to/#/#opensaps:pztrn.name) Matrix room for help and chat! -# Installation +## Installation ``` go get -u -v -d gitlab.com/pztrn/opensaps @@ -15,28 +15,30 @@ go install -v gitlab.com/pztrn/opensaps Or drop into [tags section](https://gitlab.com/pztrn/opensaps/tags) to grab a precompiled binary! -# Configuration +## Configuration -Take a look at ``opensaps.example.yaml`` for configuration example. Right now there is no documentation about configuration file, but it will appear in future. +Take a look at ``opensaps.example.yaml`` for configuration example and into [docs section](/doc/configuration.md) for configuration file fields description. -# Usage +## Usage The only parameter OpenSAPS binary accepts is a configuration file path. Do it like: -``` +```bash opensaps -config /path/to/opensaps.yaml ``` -There is some documentation available - check out ``doc`` directory! - -# About hooks and parsers +## About hooks and parsers While configuring a webhook in your application, please, set username exactly same as one of parsers in ``parsers`` directory! Otherwise parser "default" will be used, which will just concatenate text and attachments into one message! -Also note - that nickname will be ignored while sending message to pushers. +Also note - that nickname will be ignored while sending message to pushers. Nickname under which messages will appear depends on your account's configuration. + +## Known to work good software + +[There is a list of software](/doc/software_that_works_good.md) that known to work fine with OpenSAPS. Check it out! ---- -# IMPORTANT NOTICE +## IMPORTANT NOTICE This project isn't affiliated nor developed by Slack itself. diff --git a/doc/configuration.md b/doc/configuration.md index 7a1c707..eba40ae 100644 --- a/doc/configuration.md +++ b/doc/configuration.md @@ -2,11 +2,11 @@ There is no hardcoded place for OpenSAPS configuration. You **should** provide path to configuration file via ``-config`` parameter. -# Example configuration +## Example configuration Example can be viewed in opensaps.example.yaml, which is stored in root directory of this repository. -# Configuration values. +## Configuration values. Here we will go thru configuration values available. Nesting shows nesting level in configuration file. @@ -20,12 +20,12 @@ Here we will go thru configuration values available. Nesting shows nesting level * ``gitea_to_matrix`` - example webhook name. Should be unique and can be anything you can imagine (in text, of course). - **WARNING:** multiline webhook names wasn't tested! Try to keep your text in single line! - + **WARNING:** multiline webhook names wasn't tested! Try to keep your text in single line! + * ``slack`` - namespace for configuring Slack API parameters. URL for Slack webhook looks like: - ``` - http(s)://server.tls/services/T12345678/B87654321/24charslongstring + ```text + http(s)://server.tls/T12345678/B87654321/24charslongstring ``` Where ``12345678`` is a random 8-char string (all caps) and ``24charslongstring`` is a random 24-char string. @@ -41,15 +41,15 @@ Here we will go thru configuration values available. Nesting shows nesting level * ``remote`` - configures pusher this webhook should use and connection name for it. - * ``pusher`` - what pusher this webhook should use. + * ``pusher`` - what pusher (protocol) this webhook should use to retransmit received data. - * ``push_to`` - connection name for this pusher. + * ``push_to`` - connection name for this pusher. It should be defined below for pusher defined above. * ``matrix`` - configures Matrix pusher connections available. * ``matrix_test`` - connection name. Should be unique and can be anything you can imagine (in text, of course). - **WARNING:** multiline webhook names wasn't tested! Try to keep your text in single line! + **WARNING:** multiline webhook names wasn't tested! Try to keep your text in single line! * ``api_root`` - API root for Matrix connection. For example, ``https://localhost:8448/_matrix/client/r0``. @@ -63,19 +63,19 @@ Here we will go thru configuration values available. Nesting shows nesting level * ``telegram`` - configures Telegram pusher connections. * ``telegram_test`` - connection name. Should be unique and can be anything you can imagine (in text, of course). - + * ``bot_id`` - token from BotFather. - - * ``chat_id`` - chat ID to where OpenSAPS will write message. Easies way to get it - invite bot into chat (or start chat with bot), send a message and go to https://api.telegram.org/botYOUR:BOTTOKEN/getUpdates to obtain chat ID. It can be positive (for privates) and negative (for groupchats). - + + * ``chat_id`` - chat ID to where OpenSAPS will write message. Easies way to get it - invite bot into chat (or start chat with bot), send a message and go to to obtain chat ID. It can be positive (for privates) and negative (for groupchats). + * ``proxy`` - proxy configuration for Telegram connection. This configuration is **connection-specific**. * ``enabled`` - should we use proxy or not. - + * ``type`` - proxy type. For now ignored as only HTTP proxy support is available. - + * ``address`` - proxy server address in format "address:port". - + * ``user`` - this username will be used for authorization if filled. - + * ``password`` - this password will be used for authorization if filled **and** if username is also filled. \ No newline at end of file diff --git a/doc/software_that_works_good.md b/doc/software_that_works_good.md new file mode 100644 index 0000000..bae6a60 --- /dev/null +++ b/doc/software_that_works_good.md @@ -0,0 +1,10 @@ +# Software that works good + +Here goes a list of software that works good with OpenSAPS. + +If there is a need of additional configuration and/or patches - it will be mentioned. + +Create PR if you want to add software here. + +* [Gitea](https://gitea.io) - works fine with default parser. +* [Gitlab](https://gitlab.com) both gitlab.com and self-hosted - works fine with default parser. \ No newline at end of file