From 6766ea0ff362a251376781993e7741cc68c09a3b Mon Sep 17 00:00:00 2001 From: Martin Rotter Date: Fri, 29 Sep 2023 07:27:53 +0200 Subject: [PATCH] work on docs --- docs/source/_static/style.css | 3 + docs/source/_templates/layout.html | 4 + docs/source/conf.py | 29 +- docs/source/donations.md | 3 + docs/source/donations.rst | 6 - docs/source/downloads.md | 11 + docs/source/downloads.rst | 12 - docs/source/features/filters.md | 261 ++++++++++++++++++ docs/source/features/gui-concepts.md | 27 ++ docs/source/features/images/account-menu.png | Bin 0 -> 8383 bytes docs/source/features/images/accounts.png | Bin 0 -> 20425 bytes docs/source/features/images/feed-details.png | Bin 0 -> 23099 bytes .../source/features/images/filters-dialog.png | Bin 0 -> 71652 bytes .../features/images/rssguard-window.png | Bin 0 -> 63216 bytes docs/source/index.rst | 14 +- docs/source/requirements.txt | 1 + docs/source/supported-os.md | 8 + docs/source/supported-os.rst | 9 - docs/source/supported-readers.md | 29 ++ docs/source/supported-readers.rst | 32 --- docs/source/what.md | 3 + docs/source/what.rst | 6 - 22 files changed, 388 insertions(+), 70 deletions(-) create mode 100644 docs/source/_static/style.css create mode 100644 docs/source/_templates/layout.html create mode 100644 docs/source/donations.md delete mode 100644 docs/source/donations.rst create mode 100644 docs/source/downloads.md delete mode 100644 docs/source/downloads.rst create mode 100644 docs/source/features/filters.md create mode 100644 docs/source/features/gui-concepts.md create mode 100644 docs/source/features/images/account-menu.png create mode 100644 docs/source/features/images/accounts.png create mode 100644 docs/source/features/images/feed-details.png create mode 100644 docs/source/features/images/filters-dialog.png create mode 100644 docs/source/features/images/rssguard-window.png create mode 100644 docs/source/supported-os.md delete mode 100644 docs/source/supported-os.rst create mode 100644 docs/source/supported-readers.md delete mode 100644 docs/source/supported-readers.rst create mode 100644 docs/source/what.md delete mode 100644 docs/source/what.rst diff --git a/docs/source/_static/style.css b/docs/source/_static/style.css new file mode 100644 index 000000000..726fb5238 --- /dev/null +++ b/docs/source/_static/style.css @@ -0,0 +1,3 @@ +.wy-nav-content { + max-width: none !important; +} \ No newline at end of file diff --git a/docs/source/_templates/layout.html b/docs/source/_templates/layout.html new file mode 100644 index 000000000..7488ec4aa --- /dev/null +++ b/docs/source/_templates/layout.html @@ -0,0 +1,4 @@ +{% extends "!layout.html" %} +{% block extrahead %} + +{% endblock %} \ No newline at end of file diff --git a/docs/source/conf.py b/docs/source/conf.py index f16cf5ae6..742444bfc 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -10,7 +10,7 @@ author = 'Martin Rotter' # -- General configuration --------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration -extensions = ['sphinx.ext.extlinks'] +extensions = ['myst_parser', 'sphinx.ext.extlinks'] templates_path = ['_templates'] exclude_patterns = [ 'old_docs' ] @@ -20,4 +20,29 @@ exclude_patterns = [ 'old_docs' ] html_theme = 'sphinx_rtd_theme' html_static_path = ['_static'] html_logo = '../../resources/graphics/rssguard.png' -html_favicon = '../../resources/graphics/rssguard.ico' \ No newline at end of file +html_favicon = '../../resources/graphics/rssguard.ico' + +html_theme_options = { + 'collapse_navigation': False, + 'sticky_navigation': True, + 'navigation_depth': -1, + 'includehidden': True, + 'titles_only': False +} + +myst_enable_extensions = [ + "amsmath", + "attrs_inline", + "colon_fence", + "deflist", + "dollarmath", + "fieldlist", + "html_admonition", + "html_image", + "linkify", + "replacements", + "smartquotes", + "strikethrough", + "substitution", + "tasklist", +] \ No newline at end of file diff --git a/docs/source/donations.md b/docs/source/donations.md new file mode 100644 index 000000000..8c723736a --- /dev/null +++ b/docs/source/donations.md @@ -0,0 +1,3 @@ +Donations +========= +You can support author of RSS Guard via [donations](https://github.com/sponsors/martinrotter). \ No newline at end of file diff --git a/docs/source/donations.rst b/docs/source/donations.rst deleted file mode 100644 index 9debd017b..000000000 --- a/docs/source/donations.rst +++ /dev/null @@ -1,6 +0,0 @@ -:tocdepth: 2 - -Donations -========= - -You can support author of RSS Guard via `donations https://github.com/sponsors/martinrotter`. \ No newline at end of file diff --git a/docs/source/downloads.md b/docs/source/downloads.md new file mode 100644 index 000000000..7c0f847ad --- /dev/null +++ b/docs/source/downloads.md @@ -0,0 +1,11 @@ +Downloads +========= +Official place to download RSS Guard is at [Github Releases page](https://github.com/martinrotter/rssguard/releases). You can also download the [development (beta) build](https://github.com/martinrotter/rssguard/releases/tag/devbuild), which is updated automatically every time the source code is updated. + +RSS Guard is also available in [repositories of many Linux distributions](https://repology.org/project/rssguard/versions), and via [Flathub](https://flathub.org/about). + +The are two different flavors: +* [Regular](https://flathub.org/apps/details/io.github.martinrotter.rssguard): Includes an (almost) full-blown integrated web browser (built with `-DUSE_WEBENGINE=ON`). +* [Lite](https://flathub.org/apps/details/io.github.martinrotter.rssguardlite): Includes simpler, safer (and less memory hungry integrated web browser (built with `-DUSE_WEBENGINE=OFF`). + +I highly recommend to download RSS Guard only from trusted sources. \ No newline at end of file diff --git a/docs/source/downloads.rst b/docs/source/downloads.rst deleted file mode 100644 index 978253a38..000000000 --- a/docs/source/downloads.rst +++ /dev/null @@ -1,12 +0,0 @@ -Downloads -========= - -Official place to download RSS Guard is at `Github Releases page `_. You can also download the `development (beta) build `_, which is updated automatically every time the source code is updated. - -RSS Guard is also available in `repositories of many Linux distributions `_, and via `Flathub `_. - -The are two different flavors: - * `Regular `_: Includes an (almost) full-blown integrated web browser (built with ``-DUSE_WEBENGINE=ON``). - * `Lite `_: Includes simpler, safer (and less memory hungry integrated web browser (built with ``-DUSE_WEBENGINE=OFF``). - -I highly recommend to download RSS Guard only from trusted sources. \ No newline at end of file diff --git a/docs/source/features/filters.md b/docs/source/features/filters.md new file mode 100644 index 000000000..d827e14de --- /dev/null +++ b/docs/source/features/filters.md @@ -0,0 +1,261 @@ +Article Filtering +================= +Sometimes you need to automatically tweak the incoming article - mark it starred, remove ads from its contents, or simply ignore it. That's where article filtering feature comes in. + +## `Article filters` dialog +The dialog seen below offers you a way of managing your article filters. You can assign single filter to multiple feeds. + +`Test` button tests selected filter against existing messages. `Process checked feeds` runs the filter against messages from checked feeds. + +alt-img + +## Writing article filter +Article filters are small scripts which are executed automatically when articles/feeds are downloaded. Article filters are `JavaScript` pieces of code which must provide function with prototype: + +```js +function filterMessage() { } +``` + +The function should be fast and must return values which belong to enumeration `FilteringAction`. + +Each article is accessible in your script via global variable named `msg` of type `MessageObject`, see [this file](https://github.com/martinrotter/rssguard/blob/master/src/librssguard/core/messageobject.h) for the declaration. Some properties are writeable, allowing you to change contents of the article before it is written to RSS Guard DB. You can mark article important, change its description, perhaps change author name or even assign some label to it!!! + +Some attributes (`read/unread/starred` states) are synchronized back to your account's server - so you can for example mark some articles as starred and the change will be propagated back to TT-RSS server if you use TT-RSS. + +A special placeholders can be used in article filters. + +There is also a special variable named `utils`. This variable is of `FilterUtils` type. It offers some useful utility functions for you to use in your filters. + +Labels assigned to articles are visible to your filters. You can, therefore, execute actions in your filtering script, based on which labels are assigned to the article. The property is called `assignedLabels` and is an array of the `Label` objects. + +Passed article also offers a special function: + +```js +Boolean MessageObject.isAlreadyInDatabase(DuplicateCheck) +``` + +which allows you to perform runtime check for existence of the article in RSS Guard's database. Parameter is the value from enumeration `DuplicateCheck`. It specifies how exactly the article should match. + +For example, if you want to check if there is already another article by the same author in a database, you should call `msg.isAlreadyInDatabase(MessageObject.SameAuthor)`. +The values of enumeration can be combined in a single call with the [bitwise OR](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Bitwise_OR) (`|`) operator, like this: + +```js +msg.isAlreadyInDatabase(MessageObject.SameAuthor | MessageObject.SameUrl) +``` + +## Class Reference Documentation + +Here is the reference of methods and properties of types available in your filtering scripts. + +### `MessageObject` class +| Type | Name(Parameters) | Return value | Read-only | Synchronized | Description +| :--- | :--- | :--- | :---: | :---: | --- +| Property | `assignedLabels` | `Array