From 44593b6697b87bd8820f3cdff6522de9a956656f Mon Sep 17 00:00:00 2001 From: J0J0 Todos Date: Fri, 26 Jul 2024 11:57:16 +0200 Subject: [PATCH 01/72] Set docs TOC to show subcommands and remove useless Contents heading --- doc/source/index_cli_reference.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/doc/source/index_cli_reference.rst b/doc/source/index_cli_reference.rst index d64ba248..29154c3d 100644 --- a/doc/source/index_cli_reference.rst +++ b/doc/source/index_cli_reference.rst @@ -2,8 +2,7 @@ Command Line Reference ====================== .. toctree:: - :maxdepth: 1 - :caption: Contents: + :maxdepth: 3 synadm.cli.root synadm.cli.config From 5983bcbea3f58156b8a9018672a9df3ab9e7bda9 Mon Sep 17 00:00:00 2001 From: J0J0 Todos Date: Fri, 26 Jul 2024 12:01:23 +0200 Subject: [PATCH 02/72] Remove useless Contents heading in package docs --- doc/source/index.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/doc/source/index.rst b/doc/source/index.rst index 0a395577..9e77a6c1 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -8,7 +8,6 @@ Welcome to synadm's documentation! .. toctree:: :maxdepth: 2 - :caption: Contents: index_cli_reference examples From 4ac4947e8d82bd6a6a8d2ef5bff1a6f2b3b60361 Mon Sep 17 00:00:00 2001 From: J0J0 Todos Date: Sat, 27 Jul 2024 11:07:15 +0200 Subject: [PATCH 03/72] Add to docs an API/Command overview as a table --- doc/source/conf.py | 2 +- doc/source/features.csv | 22 ++++++++++++++++++++++ doc/source/features.rst | 8 ++++++++ doc/source/index.rst | 1 + 4 files changed, 32 insertions(+), 1 deletion(-) create mode 100644 doc/source/features.csv create mode 100644 doc/source/features.rst diff --git a/doc/source/conf.py b/doc/source/conf.py index 2c2c09f0..75416937 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -71,7 +71,7 @@ 'collapse_navigation': True, 'navigation_depth': 8, 'sticky_navigation': False, - 'prev_next_buttons_location': 'both' + 'prev_next_buttons_location': 'bottom' } diff --git a/doc/source/features.csv b/doc/source/features.csv new file mode 100644 index 00000000..b21b0d32 --- /dev/null +++ b/doc/source/features.csv @@ -0,0 +1,22 @@ +Synapse API,synadm command group(s) +`Acount Validity `_, +`Delete Group `_,`synadm group `_ +`Event Reports `_, +`Media Admin `_,"* `synadm media `_ +* `synadm user `_" +`Purge History `_,`synadm history `_ +`Purge Room `_,`synadm room `_ +`Register `_, +`Room Membership `_,`synadm room `_ +`Rooms `_,`synadm room `_ +`Server Notices `_,`synadm notice `_ +`Statistics `_, +`User Admin `_,`synadm user `_ +`Version `_,`synadm version `_ +`Registration Tokens `_,`synadm regtok `_ +`Background Update `_, +`Èxperimental Features `_, +`Federation `_, +,`synadm config `_ +,`synadm raw `_ +,`synadm matrix `_ diff --git a/doc/source/features.rst b/doc/source/features.rst new file mode 100644 index 00000000..a8f13463 --- /dev/null +++ b/doc/source/features.rst @@ -0,0 +1,8 @@ +API Coverage +========================= + +.. csv-table:: Admin API vs Command Overview + :file: features.csv + :header-rows: 1 + :class: longtable + :widths: 1 1 diff --git a/doc/source/index.rst b/doc/source/index.rst index 9e77a6c1..ecb22115 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -10,6 +10,7 @@ Welcome to synadm's documentation! :maxdepth: 2 index_cli_reference + features examples index_modules From a8b9f47d791e7af3e9f97e194b6a0def877c3029 Mon Sep 17 00:00:00 2001 From: J0J0 Todos Date: Sat, 3 Aug 2024 14:08:10 +0200 Subject: [PATCH 04/72] Fix typo in features.csv --- doc/source/features.csv | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/features.csv b/doc/source/features.csv index b21b0d32..a616bf3c 100644 --- a/doc/source/features.csv +++ b/doc/source/features.csv @@ -15,7 +15,7 @@ Synapse API,synadm command group(s) `Version `_,`synadm version `_ `Registration Tokens `_,`synadm regtok `_ `Background Update `_, -`Èxperimental Features `_, +`Experimental Features `_, `Federation `_, ,`synadm config `_ ,`synadm raw `_ From 4e50a99e4e36999709dd611a32f8bb2f967aa968 Mon Sep 17 00:00:00 2001 From: J0J0 Todos Date: Sat, 3 Aug 2024 14:09:21 +0200 Subject: [PATCH 05/72] No bulletpoints in features.csv - ugly --- doc/source/features.csv | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/source/features.csv b/doc/source/features.csv index a616bf3c..c115429b 100644 --- a/doc/source/features.csv +++ b/doc/source/features.csv @@ -2,8 +2,8 @@ Synapse API,synadm command group(s) `Acount Validity `_, `Delete Group `_,`synadm group `_ `Event Reports `_, -`Media Admin `_,"* `synadm media `_ -* `synadm user `_" +`Media Admin `_,"`synadm media `_ +`synadm user `_" `Purge History `_,`synadm history `_ `Purge Room `_,`synadm room `_ `Register `_, From f55c9b4aed9595f7246681fb8be1980601346325 Mon Sep 17 00:00:00 2001 From: J0J0 Todos Date: Sat, 3 Aug 2024 14:12:00 +0200 Subject: [PATCH 06/72] Fix media api link worded as in Synapse docs Word our links exactly as the chapters/toc links in Synapse docs are! --- doc/source/features.csv | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/features.csv b/doc/source/features.csv index c115429b..5d250b54 100644 --- a/doc/source/features.csv +++ b/doc/source/features.csv @@ -2,7 +2,7 @@ Synapse API,synadm command group(s) `Acount Validity `_, `Delete Group `_,`synadm group `_ `Event Reports `_, -`Media Admin `_,"`synadm media `_ +`Media `_,"`synadm media `_ `synadm user `_" `Purge History `_,`synadm history `_ `Purge Room `_,`synadm room `_ From 15e89df27522da2b1b216fece79b3a4dcdcf4b79 Mon Sep 17 00:00:00 2001 From: J0J0 Todos Date: Sat, 3 Aug 2024 16:16:52 +0200 Subject: [PATCH 07/72] In features.csv play around with linking in rst syntax. Seems like linking to a :ref: is not possible, because sphinx-click does not generate one, or I don't know what it's called. Linking to a whole doc is possible, as this commit does. Not what we want but leave for reference. --- doc/source/features.csv | 1 + 1 file changed, 1 insertion(+) diff --git a/doc/source/features.csv b/doc/source/features.csv index 5d250b54..346351d5 100644 --- a/doc/source/features.csv +++ b/doc/source/features.csv @@ -4,6 +4,7 @@ Synapse API,synadm command group(s) `Event Reports `_, `Media `_,"`synadm media `_ `synadm user `_" +`List all media in a room `_,:doc:`synadm.cli.media` `Purge History `_,`synadm history `_ `Purge Room `_,`synadm room `_ `Register `_, From 161bbbe8ec68a41794b4336cb57338ea2f7d0075 Mon Sep 17 00:00:00 2001 From: J0J0 Todos Date: Sat, 3 Aug 2024 21:20:55 +0200 Subject: [PATCH 08/72] In features.csv link to EVERY single Admin API in the left column. Use proper rst Syntax in the right column. Unfortunately we have to work around this bug: https://github.com/click-contrib/sphinx-click/issues/15 Bug description in short: Only linking to cli-options possible, not to entire cli-commands. Eg. `synadm room list -i` works but `synadm room list` does not! --- doc/source/features.csv | 59 +++++++++++++++++++++++++---------------- 1 file changed, 36 insertions(+), 23 deletions(-) diff --git a/doc/source/features.csv b/doc/source/features.csv index 346351d5..d1eac56b 100644 --- a/doc/source/features.csv +++ b/doc/source/features.csv @@ -1,23 +1,36 @@ -Synapse API,synadm command group(s) -`Acount Validity `_, -`Delete Group `_,`synadm group `_ -`Event Reports `_, -`Media `_,"`synadm media `_ -`synadm user `_" -`List all media in a room `_,:doc:`synadm.cli.media` -`Purge History `_,`synadm history `_ -`Purge Room `_,`synadm room `_ -`Register `_, -`Room Membership `_,`synadm room `_ -`Rooms `_,`synadm room `_ -`Server Notices `_,`synadm notice `_ -`Statistics `_, -`User Admin `_,`synadm user `_ -`Version `_,`synadm version `_ -`Registration Tokens `_,`synadm regtok `_ -`Background Update `_, -`Experimental Features `_, -`Federation `_, -,`synadm config `_ -,`synadm raw `_ -,`synadm matrix `_ +Synapse Admin API,synadm command group / synadm command +`Acount Validity APIs Overview `_, +- `Renew account `_, +"`Delete Group API [dead, API gone?] `_",- :doc:`synadm.cli.group` +`Background Update APIs Overview `_, +- `Event Reports APIs Overview `_, +- `Show reported events `_, +- `Show details of a specific event report `_, +- `Delete a specific event report `_, +`Experimental Features APIs Overview `_, +`Media APIs Overview `_,"- :doc:`synadm.cli.media` +- :doc:`synadm.cli.user`" +- `List all media in a room `_,- :option:`synadm media list -r` +- `List all media uploaded by a user `_,"- :option:`synadm media list -u` +- :option:`synadm user media -f`" +`Purge History APIs Overview `_,- :doc:`synadm.cli.history` +- `Purge history `_,- :option:`synadm history purge -i` +- `Purge status query `_,- :option:`synadm history purge-status PURGE_ID` +`Register Users APIs Overview `_, +- `Shared-Secret Registration `_, +`Registration Tokens APIs Overview `_,- :doc:`synadm.cli.regtok` +`Manipulate Room Membership API `_,- :doc:`synadm.cli.room` +- `Edit Room Membership API `_,- :option:`synadm room join ROOM_ID_OR_ALIAS` +`Rooms APIs Overview `_,- :doc:`synadm.cli.room` +- `List Room API `_,- :option:`synadm room list -f` +- `Room Details API `_,- :option:`synadm room details ROOM_ID` +- `Room Members API `_,- :option:`synadm room members ROOM_ID` +...and so on....we have a lot of Room APIs....,...and synadm room commands..... +`Server Notices APIs Overview `_,- :doc:`synadm.cli.notice` +`Statistics APIs Overview `_, +`User Admin APIs Overview `_,- :doc:`synadm.cli.user` +`Server Version API `_,- :option:`synadm --version` +`Federation APIs Overview `_, +,- :doc:`synadm.cli.config` +,- :doc:`synadm.cli.raw` +,- :doc:`synadm.cli.matrix` From 7deb008c3f0f5e833630bb5e0e8b370c0bb88021 Mon Sep 17 00:00:00 2001 From: J0J0 Todos Date: Mon, 5 Aug 2024 11:51:10 +0200 Subject: [PATCH 09/72] features.csv fix Delete Group API docs link and for now leave latest Synapse version in link description. TBD how to handle deprecated/removed API's. --- doc/source/features.csv | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/features.csv b/doc/source/features.csv index d1eac56b..4d06be8a 100644 --- a/doc/source/features.csv +++ b/doc/source/features.csv @@ -1,7 +1,7 @@ Synapse Admin API,synadm command group / synadm command `Acount Validity APIs Overview `_, - `Renew account `_, -"`Delete Group API [dead, API gone?] `_",- :doc:`synadm.cli.group` +`Delete Group API [Synapse 1.6.1] `_,- :doc:`synadm.cli.group` `Background Update APIs Overview `_, - `Event Reports APIs Overview `_, - `Show reported events `_, From f85224ae076f5f43acb737b4948b80d01a71528b Mon Sep 17 00:00:00 2001 From: J0J0 Todos Date: Mon, 5 Aug 2024 14:27:38 +0200 Subject: [PATCH 10/72] Add a scraper gathering Admin API docs links A first draft. Gets all anchors but only if a direct parent is a header tag. --- scrape_docs.py | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) create mode 100755 scrape_docs.py diff --git a/scrape_docs.py b/scrape_docs.py new file mode 100755 index 00000000..1bd00c22 --- /dev/null +++ b/scrape_docs.py @@ -0,0 +1,31 @@ +#!/usr/bin/env python + +from bs4 import BeautifulSoup +import requests +import re +import pprint as p + + +chapter = 'https://element-hq.github.io/synapse/develop/admin_api/rooms.html' +apidoc = requests.get(chapter).text +soup = BeautifulSoup(apidoc, 'html.parser') + +elements = soup.find_all( + ['h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'a'], +) + +#p.pprint(elements) +for e in elements: + if e.name in ['h1', 'h2', 'h3', 'h4', 'h5', 'h6']: + print(f'HEADLINE {e.name}: {e.text}') + if e.name == 'a': + if e.parent.name in ['h1', 'h2', 'h3', 'h4', 'h5', 'h6']: + link = e['href'] + print(f'{e.text} {link}') + print() + +print() +print() +print() + +#print(soup.prettify()) From c549c2ca697e695c087a603f5840c9512caf9eb5 Mon Sep 17 00:00:00 2001 From: J0J0 Todos Date: Tue, 6 Aug 2024 09:00:59 +0200 Subject: [PATCH 11/72] Build a minimalistic Click cli around scraper --- scrape_docs.py | 52 ++++++++++++++++++++++++++++++++------------------ 1 file changed, 33 insertions(+), 19 deletions(-) diff --git a/scrape_docs.py b/scrape_docs.py index 1bd00c22..cd456fdb 100755 --- a/scrape_docs.py +++ b/scrape_docs.py @@ -1,31 +1,45 @@ #!/usr/bin/env python +import click from bs4 import BeautifulSoup import requests import re import pprint as p +@click.command() +@click.option( + '--output', '-o', default='default', type=click.Choice(['default', 'csv']), + show_choices=True, help=f'''Output format "default" prints human readable + on shell, "csv" is a two-column comma separated value format.''') +@click.argument('URL') +def scrape(output, url): + '''Scrape one chapter of Admin API docs and spit out in various formats. -chapter = 'https://element-hq.github.io/synapse/develop/admin_api/rooms.html' -apidoc = requests.get(chapter).text -soup = BeautifulSoup(apidoc, 'html.parser') + URL is the address of the Synapse Admin API docs chapter. For example: + https://element-hq.github.io/synapse/develop/admin_api/rooms.html''' + chapter = url + apidoc = requests.get(chapter).text + soup = BeautifulSoup(apidoc, 'html.parser') -elements = soup.find_all( - ['h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'a'], -) + elements = soup.find_all( + ['h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'a'], + ) -#p.pprint(elements) -for e in elements: - if e.name in ['h1', 'h2', 'h3', 'h4', 'h5', 'h6']: - print(f'HEADLINE {e.name}: {e.text}') - if e.name == 'a': - if e.parent.name in ['h1', 'h2', 'h3', 'h4', 'h5', 'h6']: - link = e['href'] - print(f'{e.text} {link}') - print() - -print() -print() -print() + #p.pprint(elements) + for e in elements: + if e.name in ['h1', 'h2', 'h3', 'h4', 'h5', 'h6']: + print(f'HEADLINE {e.name}: {e.text}') + if e.name == 'a': + if e.parent.name in ['h1', 'h2', 'h3', 'h4', 'h5', 'h6']: + link = e['href'] + print(f'{e.text} {link}') + print() + print() + print() + print() #print(soup.prettify()) + + +if __name__ == '__main__': + scrape() From 9ad9beee1e4cd2468b85bcb54fad30f80f94f879 Mon Sep 17 00:00:00 2001 From: J0J0 Todos Date: Tue, 6 Aug 2024 09:27:30 +0200 Subject: [PATCH 12/72] Add rst output format to scraper --- scrape_docs.py | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/scrape_docs.py b/scrape_docs.py index cd456fdb..a5fa8365 100755 --- a/scrape_docs.py +++ b/scrape_docs.py @@ -8,7 +8,7 @@ @click.command() @click.option( - '--output', '-o', default='default', type=click.Choice(['default', 'csv']), + '--output', '-o', default='default', type=click.Choice(['default', 'rst', 'csv']), show_choices=True, help=f'''Output format "default" prints human readable on shell, "csv" is a two-column comma separated value format.''') @click.argument('URL') @@ -28,11 +28,17 @@ def scrape(output, url): #p.pprint(elements) for e in elements: if e.name in ['h1', 'h2', 'h3', 'h4', 'h5', 'h6']: - print(f'HEADLINE {e.name}: {e.text}') + if output in ['default', 'rst']: + print(f'{e.name}: {e.text}') if e.name == 'a': if e.parent.name in ['h1', 'h2', 'h3', 'h4', 'h5', 'h6']: link = e['href'] - print(f'{e.text} {link}') + if output == 'default': + print(f'{e.text} {link}') + if output == 'rst': + parts = chapter.split('admin_api') + fulllink = f'{parts[0]}admin_api{parts[1]}{link}' + print(f'`{e.text} <{fulllink}>`') print() print() From 926b3a6833a13c91cb1d18fcfa335ec2a347666d Mon Sep 17 00:00:00 2001 From: J0J0 Todos Date: Tue, 6 Aug 2024 10:12:56 +0200 Subject: [PATCH 13/72] Finally add csv output to scraper and fix rst output format (trailing underscore) --- scrape_docs.py | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) diff --git a/scrape_docs.py b/scrape_docs.py index a5fa8365..22ae5d78 100755 --- a/scrape_docs.py +++ b/scrape_docs.py @@ -35,15 +35,20 @@ def scrape(output, url): link = e['href'] if output == 'default': print(f'{e.text} {link}') - if output == 'rst': + if output in ['rst', 'csv']: parts = chapter.split('admin_api') fulllink = f'{parts[0]}admin_api{parts[1]}{link}' - print(f'`{e.text} <{fulllink}>`') + if output == 'rst': + rst = f'`{e.text} <{fulllink}>`_' + print(rst) + # csv format also adds some spacing in front of links + if output == 'csv': + left_col = f' `{e.text} <{fulllink}>`_' + print(f'{left_col},') + # Final spacing only with these formats + if output in ['default', 'rst']: print() - print() - print() - print() #print(soup.prettify()) From c7cabf6fa464aa2b40d8a7f98e536fd96e432237 Mon Sep 17 00:00:00 2001 From: J0J0 Todos Date: Tue, 6 Aug 2024 11:09:16 +0200 Subject: [PATCH 14/72] Again decide that bulletpoints in a table are ugly fix existing data to use two spaces for indentation of subordinate api docs links and remove bulletpoints entirely in right column. --- doc/source/features.csv | 78 ++++++++++++++++++++++++++--------------- 1 file changed, 50 insertions(+), 28 deletions(-) diff --git a/doc/source/features.csv b/doc/source/features.csv index 4d06be8a..11d119e1 100644 --- a/doc/source/features.csv +++ b/doc/source/features.csv @@ -1,36 +1,58 @@ Synapse Admin API,synadm command group / synadm command `Acount Validity APIs Overview `_, -- `Renew account `_, -`Delete Group API [Synapse 1.6.1] `_,- :doc:`synadm.cli.group` +" `Renew account `_", +`Delete Group API [Synapse 1.6.1] `_,:doc:`synadm.cli.group` `Background Update APIs Overview `_, -- `Event Reports APIs Overview `_, -- `Show reported events `_, -- `Show details of a specific event report `_, -- `Delete a specific event report `_, +`Event Reports APIs Overview `_, +" `Show reported events `_", +" `Show details of a specific event report `_", +" `Delete a specific event report `_", `Experimental Features APIs Overview `_, -`Media APIs Overview `_,"- :doc:`synadm.cli.media` -- :doc:`synadm.cli.user`" -- `List all media in a room `_,- :option:`synadm media list -r` -- `List all media uploaded by a user `_,"- :option:`synadm media list -u` -- :option:`synadm user media -f`" -`Purge History APIs Overview `_,- :doc:`synadm.cli.history` -- `Purge history `_,- :option:`synadm history purge -i` -- `Purge status query `_,- :option:`synadm history purge-status PURGE_ID` +`Media APIs Overview `_,":doc:`synadm.cli.media` +:doc:`synadm.cli.user`" +" `List all media in a room `_",:option:`synadm media list -r` +" `List all media uploaded by a user `_",":option:`synadm media list -u` +:option:`synadm user media -f`" +`Purge History APIs Overview `_,:doc:`synadm.cli.history` +" `Purge history `_",:option:`synadm history purge -i` +" `Purge status query `_",:option:`synadm history purge-status PURGE_ID` `Register Users APIs Overview `_, -- `Shared-Secret Registration `_, -`Registration Tokens APIs Overview `_,- :doc:`synadm.cli.regtok` -`Manipulate Room Membership API `_,- :doc:`synadm.cli.room` -- `Edit Room Membership API `_,- :option:`synadm room join ROOM_ID_OR_ALIAS` -`Rooms APIs Overview `_,- :doc:`synadm.cli.room` -- `List Room API `_,- :option:`synadm room list -f` -- `Room Details API `_,- :option:`synadm room details ROOM_ID` -- `Room Members API `_,- :option:`synadm room members ROOM_ID` +" `Shared-Secret Registration `_", +`Registration Tokens APIs Overview `_,:doc:`synadm.cli.regtok` +`Manipulate Room Membership API `_,:doc:`synadm.cli.room` +" `Edit Room Membership API `_",:option:`synadm room join ROOM_ID_OR_ALIAS` +`Rooms APIs Overview `_,:doc:`synadm.cli.room` +" `List Room API `_",:option:`synadm room list -f` +" `Room Details API `_",:option:`synadm room details ROOM_ID` +" `Room Members API `_",:option:`synadm room members ROOM_ID` ...and so on....we have a lot of Room APIs....,...and synadm room commands..... -`Server Notices APIs Overview `_,- :doc:`synadm.cli.notice` +`Server Notices APIs Overview `_,:doc:`synadm.cli.notice` `Statistics APIs Overview `_, -`User Admin APIs Overview `_,- :doc:`synadm.cli.user` -`Server Version API `_,- :option:`synadm --version` +`User Admin APIs Overview `_,:doc:`synadm.cli.user` +`Server Version API `_,:option:`synadm --version` `Federation APIs Overview `_, -,- :doc:`synadm.cli.config` -,- :doc:`synadm.cli.raw` -,- :doc:`synadm.cli.matrix` +,:doc:`synadm.cli.config` +,:doc:`synadm.cli.raw` +,:doc:`synadm.cli.matrix` +, +, +, +, +, +, +, +, +, +, +, +, +, +, +, +, +, +, +, +" `Check for forward extremities `_", +" `Deleting forward extremities `_", +" `Event Context API `_", From cf4d09d6427cabaa30429bfd65d5ea56dfd714ed Mon Sep 17 00:00:00 2001 From: J0J0 Todos Date: Tue, 6 Aug 2024 11:56:15 +0200 Subject: [PATCH 15/72] Add remaining room api links to features.csv with the help of scraper. --- doc/source/features.csv | 42 +++++++++++++++++++---------------------- 1 file changed, 19 insertions(+), 23 deletions(-) diff --git a/doc/source/features.csv b/doc/source/features.csv index 11d119e1..49ff41ec 100644 --- a/doc/source/features.csv +++ b/doc/source/features.csv @@ -25,7 +25,24 @@ Synapse Admin API,synadm command group / synadm command " `List Room API `_",:option:`synadm room list -f` " `Room Details API `_",:option:`synadm room details ROOM_ID` " `Room Members API `_",:option:`synadm room members ROOM_ID` -...and so on....we have a lot of Room APIs....,...and synadm room commands..... +" `Room State API `_", +" `Room Messages API `_", +" `Room Timestamp to Event API `_", +" `Block Room API `_", +" `Block or unblock a room `_", +" `Get block status `_", +" `Delete Room API `_", +" `Version 1 (old version) `_", +" `Version 2 (new version) `_", +" `Status of deleting rooms `_", +" `Query by room_id `_", +" `Query by delete_id `_", +" `Response `_", +" `Undoing room deletions `_", +" `Make Room Admin API `_", +" `Check for forward extremities `_", +" `Deleting forward extremities `_", +" `Event Context API `_", `Server Notices APIs Overview `_,:doc:`synadm.cli.notice` `Statistics APIs Overview `_, `User Admin APIs Overview `_,:doc:`synadm.cli.user` @@ -34,25 +51,4 @@ Synapse Admin API,synadm command group / synadm command ,:doc:`synadm.cli.config` ,:doc:`synadm.cli.raw` ,:doc:`synadm.cli.matrix` -, -, -, -, -, -, -, -, -, -, -, -, -, -, -, -, -, -, -, -" `Check for forward extremities `_", -" `Deleting forward extremities `_", -" `Event Context API `_", + From f718e86629f1da63cf50dc7b42416338e8db1b13 Mon Sep 17 00:00:00 2001 From: J0J0 Todos Date: Tue, 6 Aug 2024 11:57:53 +0200 Subject: [PATCH 16/72] Proper space escaping in scraper csv output --- scrape_docs.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/scrape_docs.py b/scrape_docs.py index 22ae5d78..501fae90 100755 --- a/scrape_docs.py +++ b/scrape_docs.py @@ -43,7 +43,7 @@ def scrape(output, url): print(rst) # csv format also adds some spacing in front of links if output == 'csv': - left_col = f' `{e.text} <{fulllink}>`_' + left_col = f'" `{e.text} <{fulllink}>`_"' print(f'{left_col},') # Final spacing only with these formats if output in ['default', 'rst']: From 608f1a542ca74f32479eaccf92c447540bec28f0 Mon Sep 17 00:00:00 2001 From: J0J0 Todos Date: Tue, 6 Aug 2024 13:28:55 +0200 Subject: [PATCH 17/72] Add description to features.rst and reword heading --- doc/source/features.rst | 17 +++++++++++++++-- 1 file changed, 15 insertions(+), 2 deletions(-) diff --git a/doc/source/features.rst b/doc/source/features.rst index a8f13463..a4b7bad1 100644 --- a/doc/source/features.rst +++ b/doc/source/features.rst @@ -1,8 +1,21 @@ -API Coverage -========================= +Synapse Admin API Coverage +========================== + +Below table shows which Synapse Admin APIs are used by their corresponding +``synadm`` commands. To add a newly released or otherwise missing API, edit +`features.csv`_ and submit a `pull request`_. If you happen to miss a feature +in ``synadm`` for an API that is already tracked here, file a `feature request +issue`_ or even better, a `pull request`_ implementing the feature. .. csv-table:: Admin API vs Command Overview :file: features.csv :header-rows: 1 :class: longtable :widths: 1 1 + +.. _features.csv: + https://github.com/JOJ0/synadm/tree/master/doc/source/features.csv +.. _feature request issue: + https://github.com/JOJ0/synadm/issues/new +.. _pull request: + https://github.com/JOJ0/synadm/blob/dev/CONTRIBUTING.md#submitting-your-work From ef11c1b743f61b00d13ad471d354f7d273a27757 Mon Sep 17 00:00:00 2001 From: J0J0 Todos Date: Tue, 6 Aug 2024 13:31:46 +0200 Subject: [PATCH 18/72] Remove unnecessary api docs link in features.csv and add indentation to Delete Room API subchapters --- doc/source/features.csv | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/doc/source/features.csv b/doc/source/features.csv index 49ff41ec..72771d90 100644 --- a/doc/source/features.csv +++ b/doc/source/features.csv @@ -31,13 +31,12 @@ Synapse Admin API,synadm command group / synadm command " `Block Room API `_", " `Block or unblock a room `_", " `Get block status `_", -" `Delete Room API `_", -" `Version 1 (old version) `_", -" `Version 2 (new version) `_", +" `Delete Room API Overview `_", +" `Version 1 (old version) `_", +" `Version 2 (new version) `_", " `Status of deleting rooms `_", " `Query by room_id `_", " `Query by delete_id `_", -" `Response `_", " `Undoing room deletions `_", " `Make Room Admin API `_", " `Check for forward extremities `_", From a1508330d8e5401e9d4999f5e2e4bb267cc79911 Mon Sep 17 00:00:00 2001 From: J0J0 Todos Date: Tue, 6 Aug 2024 13:52:49 +0200 Subject: [PATCH 19/72] Use doublequotes throughout csv for readability and actually even "editability". --- doc/source/features.csv | 38 +++++++++++++++++++------------------- 1 file changed, 19 insertions(+), 19 deletions(-) diff --git a/doc/source/features.csv b/doc/source/features.csv index 72771d90..5204e5c6 100644 --- a/doc/source/features.csv +++ b/doc/source/features.csv @@ -1,27 +1,27 @@ Synapse Admin API,synadm command group / synadm command -`Acount Validity APIs Overview `_, +"`Account validity APIs Overview `_", " `Renew account `_", -`Delete Group API [Synapse 1.6.1] `_,:doc:`synadm.cli.group` -`Background Update APIs Overview `_, -`Event Reports APIs Overview `_, +"`Delete Group API [Synapse 1.6.1] `_",:doc:`synadm.cli.group` +"`Background Update APIs Overview `_", +"`Event Reports APIs Overview `_", " `Show reported events `_", " `Show details of a specific event report `_", " `Delete a specific event report `_", -`Experimental Features APIs Overview `_, -`Media APIs Overview `_,":doc:`synadm.cli.media` +"`Experimental Features APIs Overview `_", +"`Media APIs Overview `_",":doc:`synadm.cli.media` :doc:`synadm.cli.user`" " `List all media in a room `_",:option:`synadm media list -r` " `List all media uploaded by a user `_",":option:`synadm media list -u` :option:`synadm user media -f`" -`Purge History APIs Overview `_,:doc:`synadm.cli.history` +"`Purge History APIs Overview `_",:doc:`synadm.cli.history` " `Purge history `_",:option:`synadm history purge -i` " `Purge status query `_",:option:`synadm history purge-status PURGE_ID` -`Register Users APIs Overview `_, +"`Register Users APIs Overview `_", " `Shared-Secret Registration `_", -`Registration Tokens APIs Overview `_,:doc:`synadm.cli.regtok` -`Manipulate Room Membership API `_,:doc:`synadm.cli.room` +"`Registration Tokens APIs Overview `_",:doc:`synadm.cli.regtok` +"`Manipulate Room Membership API `_",:doc:`synadm.cli.room` " `Edit Room Membership API `_",:option:`synadm room join ROOM_ID_OR_ALIAS` -`Rooms APIs Overview `_,:doc:`synadm.cli.room` +"`Rooms APIs Overview `_",:doc:`synadm.cli.room` " `List Room API `_",:option:`synadm room list -f` " `Room Details API `_",:option:`synadm room details ROOM_ID` " `Room Members API `_",:option:`synadm room members ROOM_ID` @@ -42,12 +42,12 @@ Synapse Admin API,synadm command group / synadm command " `Check for forward extremities `_", " `Deleting forward extremities `_", " `Event Context API `_", -`Server Notices APIs Overview `_,:doc:`synadm.cli.notice` -`Statistics APIs Overview `_, -`User Admin APIs Overview `_,:doc:`synadm.cli.user` -`Server Version API `_,:option:`synadm --version` -`Federation APIs Overview `_, -,:doc:`synadm.cli.config` -,:doc:`synadm.cli.raw` -,:doc:`synadm.cli.matrix` +"`Server Notices APIs Overview `_",:doc:`synadm.cli.notice` +"`Statistics APIs Overview `_", +"`User Admin APIs Overview `_",:doc:`synadm.cli.user` +"`Server Version API `_",:option:`synadm --version` +"`Federation APIs Overview `_", +"",:doc:`synadm.cli.config` +"",:doc:`synadm.cli.raw` +"",:doc:`synadm.cli.matrix` From a3ec1643ce68512e44da8a76591097a58bfd3313 Mon Sep 17 00:00:00 2001 From: J0J0 Todos Date: Tue, 6 Aug 2024 14:06:12 +0200 Subject: [PATCH 20/72] Remove all linebreaks (right column) in features.csv and remove "Overview" suffix for main-api-docs-links --- doc/source/features.csv | 30 ++++++++++++++---------------- 1 file changed, 14 insertions(+), 16 deletions(-) diff --git a/doc/source/features.csv b/doc/source/features.csv index 5204e5c6..d945ac2e 100644 --- a/doc/source/features.csv +++ b/doc/source/features.csv @@ -1,27 +1,25 @@ Synapse Admin API,synadm command group / synadm command -"`Account validity APIs Overview `_", +"`Account validity API `_", " `Renew account `_", "`Delete Group API [Synapse 1.6.1] `_",:doc:`synadm.cli.group` -"`Background Update APIs Overview `_", -"`Event Reports APIs Overview `_", +"`Background Update API `_", +"`Event Reports API `_", " `Show reported events `_", " `Show details of a specific event report `_", " `Delete a specific event report `_", -"`Experimental Features APIs Overview `_", -"`Media APIs Overview `_",":doc:`synadm.cli.media` -:doc:`synadm.cli.user`" +"`Experimental Features API `_", +"`Media API `_",":doc:`synadm.cli.media` :doc:`synadm.cli.user`" " `List all media in a room `_",:option:`synadm media list -r` -" `List all media uploaded by a user `_",":option:`synadm media list -u` -:option:`synadm user media -f`" -"`Purge History APIs Overview `_",:doc:`synadm.cli.history` +" `List all media uploaded by a user `_",":option:`synadm media list -u` :option:`synadm user media -f`" +"`Purge History API `_",:doc:`synadm.cli.history` " `Purge history `_",:option:`synadm history purge -i` " `Purge status query `_",:option:`synadm history purge-status PURGE_ID` -"`Register Users APIs Overview `_", +"`Register Users API `_", " `Shared-Secret Registration `_", -"`Registration Tokens APIs Overview `_",:doc:`synadm.cli.regtok` +"`Registration Tokens API `_",:doc:`synadm.cli.regtok` "`Manipulate Room Membership API `_",:doc:`synadm.cli.room` " `Edit Room Membership API `_",:option:`synadm room join ROOM_ID_OR_ALIAS` -"`Rooms APIs Overview `_",:doc:`synadm.cli.room` +"`Rooms API `_",:doc:`synadm.cli.room` " `List Room API `_",:option:`synadm room list -f` " `Room Details API `_",:option:`synadm room details ROOM_ID` " `Room Members API `_",:option:`synadm room members ROOM_ID` @@ -42,11 +40,11 @@ Synapse Admin API,synadm command group / synadm command " `Check for forward extremities `_", " `Deleting forward extremities `_", " `Event Context API `_", -"`Server Notices APIs Overview `_",:doc:`synadm.cli.notice` -"`Statistics APIs Overview `_", -"`User Admin APIs Overview `_",:doc:`synadm.cli.user` +"`Server Notices API `_",:doc:`synadm.cli.notice` +"`Statistics API `_", +"`User Admin API `_",:doc:`synadm.cli.user` "`Server Version API `_",:option:`synadm --version` -"`Federation APIs Overview `_", +"`Federation API `_", "",:doc:`synadm.cli.config` "",:doc:`synadm.cli.raw` "",:doc:`synadm.cli.matrix` From 818f716270cba72b84ffe8eb6edb818a6345d4f4 Mon Sep 17 00:00:00 2001 From: J0J0 Todos Date: Tue, 6 Aug 2024 16:16:45 +0200 Subject: [PATCH 21/72] Finally add all remaining Admin API links with the help of scrape_docs.py. Note: More than one indentation level in left column does not seem to be displayed in the final html table...no idea why...ignore! --- doc/source/features.csv | 70 +++++++++++++++++++++++++++++++++++++---- 1 file changed, 64 insertions(+), 6 deletions(-) diff --git a/doc/source/features.csv b/doc/source/features.csv index d945ac2e..deaa35d7 100644 --- a/doc/source/features.csv +++ b/doc/source/features.csv @@ -9,14 +9,33 @@ Synapse Admin API,synadm command group / synadm command " `Delete a specific event report `_", "`Experimental Features API `_", "`Media API `_",":doc:`synadm.cli.media` :doc:`synadm.cli.user`" -" `List all media in a room `_",:option:`synadm media list -r` -" `List all media uploaded by a user `_",":option:`synadm media list -u` :option:`synadm user media -f`" +" `Querying media `_","---" +" `List all media in a room `_",:option:`synadm media list -r` +" `List all media uploaded by a user `_",":option:`synadm media list -u` :option:`synadm user media -f`" +" `Quarantine media `_","---" +" `Quarantining media by ID `_", +" `Remove media from quarantine by ID `_", +" `Quarantining media in a room `_", +" `Quarantining all media of a user `_", +" `Protecting media from being quarantined `_", +" `Unprotecting media from being quarantined `_", +" `Delete local media `_","---" +" `Delete a specific local media `_", +" `Delete local media by date or size `_", +" `Delete media uploaded by a user `_", +" `Purge Remote Media API `_", "`Purge History API `_",:doc:`synadm.cli.history` " `Purge history `_",:option:`synadm history purge -i` " `Purge status query `_",:option:`synadm history purge-status PURGE_ID` "`Register Users API `_", " `Shared-Secret Registration `_", "`Registration Tokens API `_",:doc:`synadm.cli.regtok` +" `Registration token objects `_", +" `List all tokens `_", +" `Get one token `_", +" `Create token `_", +" `Update token `_", +" `Delete token `_", "`Manipulate Room Membership API `_",:doc:`synadm.cli.room` " `Edit Room Membership API `_",:option:`synadm room join ROOM_ID_OR_ALIAS` "`Rooms API `_",:doc:`synadm.cli.room` @@ -42,10 +61,49 @@ Synapse Admin API,synadm command group / synadm command " `Event Context API `_", "`Server Notices API `_",:doc:`synadm.cli.notice` "`Statistics API `_", +" `Users' media usage statistics `_", +" `Get largest rooms by size in database `_", "`User Admin API `_",:doc:`synadm.cli.user` -"`Server Version API `_",:option:`synadm --version` +" `Query User Account `_", +" `Create or modify account `_", +" `List Accounts `_", +" `List Accounts (V2) `_", +" `List Accounts (V3) `_", +" `Query current sessions for a user `_", +" `Deactivate Account `_", +" `Reset password `_", +" `Get whether a user is a server administrator or not `_", +" `Change whether a user is a server administrator or not `_", +" `List room memberships of a user `_", +" `Account Data `_", +" `User media `_", +" `List media uploaded by a user `_", +" `Delete media uploaded by a user `_", +" `Login as a user `_", +" `Allow replacing master cross-signing key without User-Interactive Auth `_", +" `User devices `_", +" `List all devices `_", +" `Create a device `_", +" `Delete multiple devices `_", +" `Show a device `_", +" `Update a device `_", +" `Delete a device `_", +" `List all pushers `_", +" `Controlling whether a user is shadow-banned `_", +" `Override ratelimiting for users `_", +" `Get status of ratelimit `_", +" `Set ratelimit `_", +" `Delete ratelimit `_", +" `Check username availability `_", +" `Find a user based on their ID in an auth provider `_", +" `Find a user based on their Third Party ID (ThreePID or 3PID) `_" +"`Version API `_",:option:`synadm --version` "`Federation API `_", -"",:doc:`synadm.cli.config` -"",:doc:`synadm.cli.raw` -"",:doc:`synadm.cli.matrix` +" `List of destinations `_", +" `Destination Details API `_", +" `Destination rooms `_", +" `Reset connection timeout `_", +"no specific api",:doc:`synadm.cli.config` +"no specific api",:doc:`synadm.cli.raw` +"no specific api",:doc:`synadm.cli.matrix` From e34f13b2dcdd4baeedca88adbcf443fd3f7161c3 Mon Sep 17 00:00:00 2001 From: J0J0 Todos Date: Tue, 6 Aug 2024 16:40:18 +0200 Subject: [PATCH 22/72] Work around indentation level problem from last commit --- doc/source/features.csv | 58 ++++++++++++++++++++--------------------- 1 file changed, 29 insertions(+), 29 deletions(-) diff --git a/doc/source/features.csv b/doc/source/features.csv index deaa35d7..c0368552 100644 --- a/doc/source/features.csv +++ b/doc/source/features.csv @@ -10,19 +10,19 @@ Synapse Admin API,synadm command group / synadm command "`Experimental Features API `_", "`Media API `_",":doc:`synadm.cli.media` :doc:`synadm.cli.user`" " `Querying media `_","---" -" `List all media in a room `_",:option:`synadm media list -r` -" `List all media uploaded by a user `_",":option:`synadm media list -u` :option:`synadm user media -f`" +" -- `List all media in a room `_",:option:`synadm media list -r` +" -- `List all media uploaded by a user `_",":option:`synadm media list -u` :option:`synadm user media -f`" " `Quarantine media `_","---" -" `Quarantining media by ID `_", -" `Remove media from quarantine by ID `_", -" `Quarantining media in a room `_", -" `Quarantining all media of a user `_", -" `Protecting media from being quarantined `_", -" `Unprotecting media from being quarantined `_", +" -- `Quarantining media by ID `_", +" -- `Remove media from quarantine by ID `_", +" -- `Quarantining media in a room `_", +" -- `Quarantining all media of a user `_", +" -- `Protecting media from being quarantined `_", +" -- `Unprotecting media from being quarantined `_", " `Delete local media `_","---" -" `Delete a specific local media `_", -" `Delete local media by date or size `_", -" `Delete media uploaded by a user `_", +" -- `Delete a specific local media `_", +" -- `Delete local media by date or size `_", +" -- `Delete media uploaded by a user `_", " `Purge Remote Media API `_", "`Purge History API `_",:doc:`synadm.cli.history` " `Purge history `_",:option:`synadm history purge -i` @@ -49,8 +49,8 @@ Synapse Admin API,synadm command group / synadm command " `Block or unblock a room `_", " `Get block status `_", " `Delete Room API Overview `_", -" `Version 1 (old version) `_", -" `Version 2 (new version) `_", +" -- `Version 1 (old version) `_", +" -- `Version 2 (new version) `_", " `Status of deleting rooms `_", " `Query by room_id `_", " `Query by delete_id `_", @@ -67,8 +67,8 @@ Synapse Admin API,synadm command group / synadm command " `Query User Account `_", " `Create or modify account `_", " `List Accounts `_", -" `List Accounts (V2) `_", -" `List Accounts (V3) `_", +" -- `List Accounts (V2) `_", +" -- `List Accounts (V3) `_", " `Query current sessions for a user `_", " `Deactivate Account `_", " `Reset password `_", @@ -77,23 +77,23 @@ Synapse Admin API,synadm command group / synadm command " `List room memberships of a user `_", " `Account Data `_", " `User media `_", -" `List media uploaded by a user `_", -" `Delete media uploaded by a user `_", +" -- `List media uploaded by a user `_", +" -- `Delete media uploaded by a user `_", " `Login as a user `_", " `Allow replacing master cross-signing key without User-Interactive Auth `_", " `User devices `_", -" `List all devices `_", -" `Create a device `_", -" `Delete multiple devices `_", -" `Show a device `_", -" `Update a device `_", -" `Delete a device `_", +" -- `List all devices `_", +" -- `Create a device `_", +" -- `Delete multiple devices `_", +" -- `Show a device `_", +" -- `Update a device `_", +" -- `Delete a device `_", " `List all pushers `_", " `Controlling whether a user is shadow-banned `_", " `Override ratelimiting for users `_", -" `Get status of ratelimit `_", -" `Set ratelimit `_", -" `Delete ratelimit `_", +" -- `Get status of ratelimit `_", +" -- `Set ratelimit `_", +" -- `Delete ratelimit `_", " `Check username availability `_", " `Find a user based on their ID in an auth provider `_", " `Find a user based on their Third Party ID (ThreePID or 3PID) `_" @@ -103,7 +103,7 @@ Synapse Admin API,synadm command group / synadm command " `Destination Details API `_", " `Destination rooms `_", " `Reset connection timeout `_", -"no specific api",:doc:`synadm.cli.config` -"no specific api",:doc:`synadm.cli.raw` -"no specific api",:doc:`synadm.cli.matrix` +"---",:doc:`synadm.cli.config` +"---",:doc:`synadm.cli.raw` +"---",:doc:`synadm.cli.matrix` From fddd8234b15947ea355730f1761bfe69b4ae9044 Mon Sep 17 00:00:00 2001 From: J0J0 Todos Date: Tue, 6 Aug 2024 16:43:49 +0200 Subject: [PATCH 23/72] Shorten two long api docs links to fix layout, otherwise left table column expands, which would render it pretty unusuble. --- doc/source/features.csv | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/source/features.csv b/doc/source/features.csv index c0368552..69a2ed4b 100644 --- a/doc/source/features.csv +++ b/doc/source/features.csv @@ -80,7 +80,7 @@ Synapse Admin API,synadm command group / synadm command " -- `List media uploaded by a user `_", " -- `Delete media uploaded by a user `_", " `Login as a user `_", -" `Allow replacing master cross-signing key without User-Interactive Auth `_", +" `Allow replacing master cross-signing key without... `_", " `User devices `_", " -- `List all devices `_", " -- `Create a device `_", @@ -96,7 +96,7 @@ Synapse Admin API,synadm command group / synadm command " -- `Delete ratelimit `_", " `Check username availability `_", " `Find a user based on their ID in an auth provider `_", -" `Find a user based on their Third Party ID (ThreePID or 3PID) `_" +" `Find a user based on their Third Party ID `_" "`Version API `_",:option:`synadm --version` "`Federation API `_", " `List of destinations `_", From 812807c632426fd4b4869a2ac133c4bb3e8dfbb9 Mon Sep 17 00:00:00 2001 From: J0J0 Todos Date: Tue, 6 Aug 2024 16:49:02 +0200 Subject: [PATCH 24/72] Fix link list-media-upload-by-a-user --- doc/source/features.csv | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/features.csv b/doc/source/features.csv index 69a2ed4b..ab2e2732 100644 --- a/doc/source/features.csv +++ b/doc/source/features.csv @@ -11,7 +11,7 @@ Synapse Admin API,synadm command group / synadm command "`Media API `_",":doc:`synadm.cli.media` :doc:`synadm.cli.user`" " `Querying media `_","---" " -- `List all media in a room `_",:option:`synadm media list -r` -" -- `List all media uploaded by a user `_",":option:`synadm media list -u` :option:`synadm user media -f`" +" -- `List all media uploaded by a user `_",":option:`synadm media list -u` :option:`synadm user media -f`" " `Quarantine media `_","---" " -- `Quarantining media by ID `_", " -- `Remove media from quarantine by ID `_", From 409bdc08e534604913a26448a7949b585531bdcb Mon Sep 17 00:00:00 2001 From: J0J0 Todos Date: Tue, 6 Aug 2024 17:34:10 +0200 Subject: [PATCH 25/72] Rename CLI reference chapter titles --- doc/source/synadm.cli.config.rst | 4 ++-- doc/source/synadm.cli.group.rst | 6 +++--- doc/source/synadm.cli.history.rst | 6 +++--- doc/source/synadm.cli.matrix.rst | 4 ++-- doc/source/synadm.cli.media.rst | 6 +++--- doc/source/synadm.cli.notice.rst | 4 ++-- doc/source/synadm.cli.raw.rst | 4 ++-- doc/source/synadm.cli.regtok.rst | 4 ++-- doc/source/synadm.cli.room.rst | 6 +++--- doc/source/synadm.cli.user.rst | 6 +++--- 10 files changed, 25 insertions(+), 25 deletions(-) diff --git a/doc/source/synadm.cli.config.rst b/doc/source/synadm.cli.config.rst index 1819a38e..490320e5 100644 --- a/doc/source/synadm.cli.config.rst +++ b/doc/source/synadm.cli.config.rst @@ -1,5 +1,5 @@ -Config -====== +Config Command +============== .. click:: synadm.cli:config_cmd :prog: synadm config diff --git a/doc/source/synadm.cli.group.rst b/doc/source/synadm.cli.group.rst index adac55f8..64d0752e 100644 --- a/doc/source/synadm.cli.group.rst +++ b/doc/source/synadm.cli.group.rst @@ -1,6 +1,6 @@ -Group -===== +Group Commands +============== .. click:: synadm.cli.group:group :prog: synadm group - :nested: full \ No newline at end of file + :nested: full diff --git a/doc/source/synadm.cli.history.rst b/doc/source/synadm.cli.history.rst index e4932bf4..b7f61a73 100644 --- a/doc/source/synadm.cli.history.rst +++ b/doc/source/synadm.cli.history.rst @@ -1,6 +1,6 @@ -History -======= +History Commands +================ .. click:: synadm.cli.history:history :prog: synadm history - :nested: full \ No newline at end of file + :nested: full diff --git a/doc/source/synadm.cli.matrix.rst b/doc/source/synadm.cli.matrix.rst index 4a657dec..c2a861f2 100644 --- a/doc/source/synadm.cli.matrix.rst +++ b/doc/source/synadm.cli.matrix.rst @@ -1,5 +1,5 @@ -Matrix -====== +Matrix Commands +=============== .. click:: synadm.cli.matrix:matrix :prog: synadm matrix diff --git a/doc/source/synadm.cli.media.rst b/doc/source/synadm.cli.media.rst index 72f84f0e..d882a912 100644 --- a/doc/source/synadm.cli.media.rst +++ b/doc/source/synadm.cli.media.rst @@ -1,6 +1,6 @@ -Media -===== +Media Commands +============== .. click:: synadm.cli.media:media :prog: synadm media - :nested: full \ No newline at end of file + :nested: full diff --git a/doc/source/synadm.cli.notice.rst b/doc/source/synadm.cli.notice.rst index 9ad75405..ceb26e69 100644 --- a/doc/source/synadm.cli.notice.rst +++ b/doc/source/synadm.cli.notice.rst @@ -1,5 +1,5 @@ -Notice -====== +Notice Commands +=============== .. click:: synadm.cli.notice:notice :prog: synadm notice diff --git a/doc/source/synadm.cli.raw.rst b/doc/source/synadm.cli.raw.rst index b386fdd2..3aef1148 100644 --- a/doc/source/synadm.cli.raw.rst +++ b/doc/source/synadm.cli.raw.rst @@ -1,5 +1,5 @@ -Raw -==== +Raw Command +=========== .. click:: synadm.cli.raw:raw_request_cmd :prog: synadm raw diff --git a/doc/source/synadm.cli.regtok.rst b/doc/source/synadm.cli.regtok.rst index d5d0f64b..f3294710 100644 --- a/doc/source/synadm.cli.regtok.rst +++ b/doc/source/synadm.cli.regtok.rst @@ -1,5 +1,5 @@ -Regtok -====== +Regtok Commands +=============== .. click:: synadm.cli.regtok:regtok :prog: synadm regtok diff --git a/doc/source/synadm.cli.room.rst b/doc/source/synadm.cli.room.rst index 8974f8b7..d4a7718e 100644 --- a/doc/source/synadm.cli.room.rst +++ b/doc/source/synadm.cli.room.rst @@ -1,6 +1,6 @@ -Room -==== +Room Commands +============= .. click:: synadm.cli.room:room :prog: synadm room - :nested: full \ No newline at end of file + :nested: full diff --git a/doc/source/synadm.cli.user.rst b/doc/source/synadm.cli.user.rst index b611a788..a79b235a 100644 --- a/doc/source/synadm.cli.user.rst +++ b/doc/source/synadm.cli.user.rst @@ -1,6 +1,6 @@ -User -==== +User Commands +============= .. click:: synadm.cli.user:user :prog: synadm user - :nested: full \ No newline at end of file + :nested: full From 5aef7ba053372d529235a630fd99a72e61f9b1b7 Mon Sep 17 00:00:00 2001 From: J0J0 Todos Date: Tue, 6 Aug 2024 17:45:35 +0200 Subject: [PATCH 26/72] Fix broken user_admin_api links which happened due to a bug in scrape_docs.py. --- doc/source/features.csv | 68 ++++++++++++++++++++--------------------- 1 file changed, 34 insertions(+), 34 deletions(-) diff --git a/doc/source/features.csv b/doc/source/features.csv index ab2e2732..9d5a0902 100644 --- a/doc/source/features.csv +++ b/doc/source/features.csv @@ -48,7 +48,7 @@ Synapse Admin API,synadm command group / synadm command " `Block Room API `_", " `Block or unblock a room `_", " `Get block status `_", -" `Delete Room API Overview `_", +" `Delete Room API `_","---" " -- `Version 1 (old version) `_", " -- `Version 2 (new version) `_", " `Status of deleting rooms `_", @@ -64,39 +64,39 @@ Synapse Admin API,synadm command group / synadm command " `Users' media usage statistics `_", " `Get largest rooms by size in database `_", "`User Admin API `_",:doc:`synadm.cli.user` -" `Query User Account `_", -" `Create or modify account `_", -" `List Accounts `_", -" -- `List Accounts (V2) `_", -" -- `List Accounts (V3) `_", -" `Query current sessions for a user `_", -" `Deactivate Account `_", -" `Reset password `_", -" `Get whether a user is a server administrator or not `_", -" `Change whether a user is a server administrator or not `_", -" `List room memberships of a user `_", -" `Account Data `_", -" `User media `_", -" -- `List media uploaded by a user `_", -" -- `Delete media uploaded by a user `_", -" `Login as a user `_", -" `Allow replacing master cross-signing key without... `_", -" `User devices `_", -" -- `List all devices `_", -" -- `Create a device `_", -" -- `Delete multiple devices `_", -" -- `Show a device `_", -" -- `Update a device `_", -" -- `Delete a device `_", -" `List all pushers `_", -" `Controlling whether a user is shadow-banned `_", -" `Override ratelimiting for users `_", -" -- `Get status of ratelimit `_", -" -- `Set ratelimit `_", -" -- `Delete ratelimit `_", -" `Check username availability `_", -" `Find a user based on their ID in an auth provider `_", -" `Find a user based on their Third Party ID `_" +" `Query User Account `_", +" `Create or modify account `_", +" `List Accounts `_","---" +" -- `List Accounts (V2) `_", +" -- `List Accounts (V3) `_", +" `Query current sessions for a user `_", +" `Deactivate Account `_", +" `Reset password `_", +" `Get whether a user is a server administrator or not `_", +" `Change whether a user is a server administrator or not `_", +" `List room memberships of a user `_", +" `Account Data `_", +" `User media `_","---" +" -- `List media uploaded by a user `_", +" -- `Delete media uploaded by a user `_", +" `Login as a user `_", +" `Allow replacing master cross-signing key without... `_", +" `User devices `_","---" +" -- `List all devices `_", +" -- `Create a device `_", +" -- `Delete multiple devices `_", +" -- `Show a device `_", +" -- `Update a device `_", +" -- `Delete a device `_", +" `List all pushers `_", +" `Controlling whether a user is shadow-banned `_", +" `Override ratelimiting for users `_","---" +" -- `Get status of ratelimit `_", +" -- `Set ratelimit `_", +" -- `Delete ratelimit `_", +" `Check username availability `_", +" `Find a user based on their ID in an auth provider `_", +" `Find a user based on their Third Party ID `_" "`Version API `_",:option:`synadm --version` "`Federation API `_", " `List of destinations `_", From 54e86c0b82a611db86b7e37cb4c15b9651d3437e Mon Sep 17 00:00:00 2001 From: J0J0 Todos Date: Tue, 6 Aug 2024 17:56:12 +0200 Subject: [PATCH 27/72] Also add user media alias below User media section and don't use doublequotes escaping. --- doc/source/features.csv | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/source/features.csv b/doc/source/features.csv index 9d5a0902..cdfd8e1f 100644 --- a/doc/source/features.csv +++ b/doc/source/features.csv @@ -8,10 +8,10 @@ Synapse Admin API,synadm command group / synadm command " `Show details of a specific event report `_", " `Delete a specific event report `_", "`Experimental Features API `_", -"`Media API `_",":doc:`synadm.cli.media` :doc:`synadm.cli.user`" +"`Media API `_",":doc:`synadm.cli.media`, :doc:`synadm.cli.user`" " `Querying media `_","---" " -- `List all media in a room `_",:option:`synadm media list -r` -" -- `List all media uploaded by a user `_",":option:`synadm media list -u` :option:`synadm user media -f`" +" -- `List all media uploaded by a user `_",:option:`synadm media list -u` :option:`synadm user media -f` " `Quarantine media `_","---" " -- `Quarantining media by ID `_", " -- `Remove media from quarantine by ID `_", @@ -78,7 +78,7 @@ Synapse Admin API,synadm command group / synadm command " `Account Data `_", " `User media `_","---" " -- `List media uploaded by a user `_", -" -- `Delete media uploaded by a user `_", +" -- `Delete media uploaded by a user `_",:option:`synadm user media -f` :option:`synadm media list -u` " `Login as a user `_", " `Allow replacing master cross-signing key without... `_", " `User devices `_","---" From 6135307a89cbdaa7521546fedb812ac9d93a65ae Mon Sep 17 00:00:00 2001 From: J0J0 Todos Date: Tue, 6 Aug 2024 18:06:20 +0200 Subject: [PATCH 28/72] Add missing experimental features api links --- doc/source/features.csv | 2 ++ 1 file changed, 2 insertions(+) diff --git a/doc/source/features.csv b/doc/source/features.csv index cdfd8e1f..ac04ecbd 100644 --- a/doc/source/features.csv +++ b/doc/source/features.csv @@ -8,6 +8,8 @@ Synapse Admin API,synadm command group / synadm command " `Show details of a specific event report `_", " `Delete a specific event report `_", "`Experimental Features API `_", +" `Enabling/Disabling Features `_", +" `Listing Enabled Features `_", "`Media API `_",":doc:`synadm.cli.media`, :doc:`synadm.cli.user`" " `Querying media `_","---" " -- `List all media in a room `_",:option:`synadm media list -r` From 1cce4a48a8896d02df66d1e4a1cc6cf85f8331b0 Mon Sep 17 00:00:00 2001 From: J0J0 Todos Date: Tue, 6 Aug 2024 18:07:29 +0200 Subject: [PATCH 29/72] Add missing group delete command --- doc/source/features.csv | 1 + 1 file changed, 1 insertion(+) diff --git a/doc/source/features.csv b/doc/source/features.csv index ac04ecbd..4130b719 100644 --- a/doc/source/features.csv +++ b/doc/source/features.csv @@ -2,6 +2,7 @@ Synapse Admin API,synadm command group / synadm command "`Account validity API `_", " `Renew account `_", "`Delete Group API [Synapse 1.6.1] `_",:doc:`synadm.cli.group` +" `Delete a local group `_",:option:`synadm group delete -h` "`Background Update API `_", "`Event Reports API `_", " `Show reported events `_", From b3bef7a847bef02ca6702baa31ccbb6f09a59599 Mon Sep 17 00:00:00 2001 From: J0J0 Todos Date: Tue, 6 Aug 2024 18:12:12 +0200 Subject: [PATCH 30/72] Add missing background updates api links --- doc/source/features.csv | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/doc/source/features.csv b/doc/source/features.csv index 4130b719..bee7a198 100644 --- a/doc/source/features.csv +++ b/doc/source/features.csv @@ -3,7 +3,10 @@ Synapse Admin API,synadm command group / synadm command " `Renew account `_", "`Delete Group API [Synapse 1.6.1] `_",:doc:`synadm.cli.group` " `Delete a local group `_",:option:`synadm group delete -h` -"`Background Update API `_", +"`Background Updates API `_", +" `Status `_", +" `Enabled `_", +" `Run `_", "`Event Reports API `_", " `Show reported events `_", " `Show details of a specific event report `_", From 09f0c1641f89a2dce652825199afb1d10abf8400 Mon Sep 17 00:00:00 2001 From: J0J0 Todos Date: Tue, 6 Aug 2024 19:44:31 +0200 Subject: [PATCH 31/72] Add remaining synadm commands to features.csv --- doc/source/features.csv | 83 +++++++++++++++++++++-------------------- 1 file changed, 42 insertions(+), 41 deletions(-) diff --git a/doc/source/features.csv b/doc/source/features.csv index bee7a198..b78d628b 100644 --- a/doc/source/features.csv +++ b/doc/source/features.csv @@ -19,90 +19,91 @@ Synapse Admin API,synadm command group / synadm command " -- `List all media in a room `_",:option:`synadm media list -r` " -- `List all media uploaded by a user `_",:option:`synadm media list -u` :option:`synadm user media -f` " `Quarantine media `_","---" -" -- `Quarantining media by ID `_", -" -- `Remove media from quarantine by ID `_", -" -- `Quarantining media in a room `_", -" -- `Quarantining all media of a user `_", -" -- `Protecting media from being quarantined `_", +" -- `Quarantining media by ID `_",:option:`synadm media quarantine -i` +" -- `Remove media from quarantine by ID `_",:option:`synadm media unquarantine -i` +" -- `Quarantining media in a room `_",:option:`synadm media quarantine -r` +" -- `Quarantining all media of a user `_",:option:`synadm media quarantine -u` +" -- `Protecting media from being quarantined `_",:option:`synadm media protect MEDIA_ID` " -- `Unprotecting media from being quarantined `_", " `Delete local media `_","---" -" -- `Delete a specific local media `_", -" -- `Delete local media by date or size `_", +" -- `Delete a specific local media `_",:option:`synadm media delete -i` +" -- `Delete local media by date or size `_",:option:`synadm media delete -d` :option:`synadm media delete --size` " -- `Delete media uploaded by a user `_", -" `Purge Remote Media API `_", +" `Purge Remote Media API `_",:option:`synadm media purge -d` "`Purge History API `_",:doc:`synadm.cli.history` " `Purge history `_",:option:`synadm history purge -i` " `Purge status query `_",:option:`synadm history purge-status PURGE_ID` "`Register Users API `_", " `Shared-Secret Registration `_", "`Registration Tokens API `_",:doc:`synadm.cli.regtok` -" `Registration token objects `_", -" `List all tokens `_", -" `Get one token `_", -" `Create token `_", -" `Update token `_", -" `Delete token `_", +" `Registration token objects `_","---" +" `List all tokens `_",:option:`synadm regtok list -v` +" `Get one token `_",:option:`synadm regtok details TOKEN` +" `Create token `_",:option:`synadm regtok new -n` +" `Update token `_",:option:`synadm regtok update TOKEN` +" `Delete token `_",:option:`synadm regtok delete TOKEN` "`Manipulate Room Membership API `_",:doc:`synadm.cli.room` " `Edit Room Membership API `_",:option:`synadm room join ROOM_ID_OR_ALIAS` "`Rooms API `_",:doc:`synadm.cli.room` " `List Room API `_",:option:`synadm room list -f` " `Room Details API `_",:option:`synadm room details ROOM_ID` " `Room Members API `_",:option:`synadm room members ROOM_ID` -" `Room State API `_", +" `Room State API `_",:option:`synadm room state ROOM_ID` " `Room Messages API `_", " `Room Timestamp to Event API `_", -" `Block Room API `_", -" `Block or unblock a room `_", -" `Get block status `_", +" `Block Room API `_","---" +" -- `Block or unblock a room `_",:option:`synadm room block -b` :option:`synadm room block -u` +" `Get block status `_",:option:`synadm room block-status ROOM_ID` " `Delete Room API `_","---" -" -- `Version 1 (old version) `_", -" -- `Version 2 (new version) `_", -" `Status of deleting rooms `_", -" `Query by room_id `_", -" `Query by delete_id `_", -" `Undoing room deletions `_", -" `Make Room Admin API `_", +" -- `Version 1 (old version) `_",:option:`synadm room delete --v1` +" -- `Version 2 (new version) `_",:option:`synadm room delete ROOM_ID` +" -- `Status of deleting rooms `_","---" +" -- `Query by room_id `_",:option:`synadm room delete-status -r` +" -- `Query by delete_id `_",:option:`synadm room delete-status -d` +" -- `Undoing room deletions `_", +" `Make Room Admin API `_",:option:`synadm room make-admin -u` " `Check for forward extremities `_", " `Deleting forward extremities `_", " `Event Context API `_", -"`Server Notices API `_",:doc:`synadm.cli.notice` +"`Server Notices `_",:doc:`synadm.cli.notice` +" `Server Notices `_",:option:`synadm notice send TO` "`Statistics API `_", " `Users' media usage statistics `_", " `Get largest rooms by size in database `_", "`User Admin API `_",:doc:`synadm.cli.user` -" `Query User Account `_", -" `Create or modify account `_", +" `Query User Account `_",:option:`synadm user details USER_ID` +" `Create or modify account `_",:option:`synadm user modify USER_ID` " `List Accounts `_","---" -" -- `List Accounts (V2) `_", +" -- `List Accounts (V2) `_",:option:`synadm user list -f` " -- `List Accounts (V3) `_", -" `Query current sessions for a user `_", -" `Deactivate Account `_", -" `Reset password `_", +" `Query current sessions for a user `_",:option:`synadm user whois USER_ID` +" `Deactivate Account `_",:option:`synadm user deactivate USER_ID` +" `Reset password `_",:option:`synadm user password USER_ID` " `Get whether a user is a server administrator or not `_", " `Change whether a user is a server administrator or not `_", -" `List room memberships of a user `_", +" `List room memberships of a user `_",:option:`synadm user membership USER_ID` " `Account Data `_", " `User media `_","---" " -- `List media uploaded by a user `_", " -- `Delete media uploaded by a user `_",:option:`synadm user media -f` :option:`synadm media list -u` -" `Login as a user `_", +" `Login as a user `_",:option:`synadm user login USER_ID` " `Allow replacing master cross-signing key without... `_", " `User devices `_","---" -" -- `List all devices `_", +" -- `List all devices `_",:option:`synadm user prune-devices --list-only` " -- `Create a device `_", -" -- `Delete multiple devices `_", -" -- `Show a device `_", +" -- `Delete multiple devices `_",:option:`synadm user prune-devices -d` :option:`synadm user prune-devices -s` +" -- `Show a device `_",:option:`synadm user prune-devices --list-only` (-i) " -- `Update a device `_", -" -- `Delete a device `_", +" -- `Delete a device `_",:option:`synadm user prune-devices -i` " `List all pushers `_", -" `Controlling whether a user is shadow-banned `_", +" `Controlling whether a user is shadow-banned `_",:option:`synadm user shadow-ban USER_ID` :option:`synadm user shadow-ban --unban` " `Override ratelimiting for users `_","---" " -- `Get status of ratelimit `_", " -- `Set ratelimit `_", " -- `Delete ratelimit `_", " `Check username availability `_", -" `Find a user based on their ID in an auth provider `_", -" `Find a user based on their Third Party ID `_" +" `Find a user based on their ID in an auth provider `_",:option:`synadm user 3pid ADDRESS` +" `Find a user based on their Third Party ID `_",:option:`synadm user auth-provider EXTERNAL_USER_ID` "`Version API `_",:option:`synadm --version` "`Federation API `_", " `List of destinations `_", From 07b9961f1541758590395d86135bec175697ffb4 Mon Sep 17 00:00:00 2001 From: J0J0 Todos Date: Tue, 6 Aug 2024 19:56:45 +0200 Subject: [PATCH 32/72] And finally describe matrix and raw commands --- doc/source/features.csv | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/doc/source/features.csv b/doc/source/features.csv index b78d628b..47c52a80 100644 --- a/doc/source/features.csv +++ b/doc/source/features.csv @@ -111,6 +111,8 @@ Synapse Admin API,synadm command group / synadm command " `Destination rooms `_", " `Reset connection timeout `_", "---",:doc:`synadm.cli.config` -"---",:doc:`synadm.cli.raw` -"---",:doc:`synadm.cli.matrix` +"Any Synapse Admin API",:doc:`synadm.cli.raw` +"Native Matrix API Helpers",:doc:`synadm.cli.matrix` +" Matrix User Login",:option:`synadm matrix login USER_ID` +" Any Matrix API",:option:`synadm matrix raw ENDPOINT` From dc0f8d2fc0666ba1130b9479368d5002baaccedf Mon Sep 17 00:00:00 2001 From: J0J0 Todos Date: Tue, 6 Aug 2024 20:04:56 +0200 Subject: [PATCH 33/72] Fix scrape_docs.py linter warnings --- scrape_docs.py | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/scrape_docs.py b/scrape_docs.py index 501fae90..0461e0cb 100755 --- a/scrape_docs.py +++ b/scrape_docs.py @@ -3,14 +3,14 @@ import click from bs4 import BeautifulSoup import requests -import re -import pprint as p + @click.command() @click.option( - '--output', '-o', default='default', type=click.Choice(['default', 'rst', 'csv']), - show_choices=True, help=f'''Output format "default" prints human readable - on shell, "csv" is a two-column comma separated value format.''') + '--output', '-o', default='default', + type=click.Choice(['default', 'rst', 'csv']), show_choices=True, + help='''Output format "default" prints human readable on shell, "csv" is a + two-column comma separated value format.''') @click.argument('URL') def scrape(output, url): '''Scrape one chapter of Admin API docs and spit out in various formats. @@ -25,7 +25,6 @@ def scrape(output, url): ['h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'a'], ) - #p.pprint(elements) for e in elements: if e.name in ['h1', 'h2', 'h3', 'h4', 'h5', 'h6']: if output in ['default', 'rst']: @@ -49,7 +48,7 @@ def scrape(output, url): if output in ['default', 'rst']: print() -#print(soup.prettify()) +# print(soup.prettify()) if __name__ == '__main__': From 7fc22f68cd44ae716a2d9d76889b03176ce91a81 Mon Sep 17 00:00:00 2001 From: J0J0 Todos <2733783+JOJ0@users.noreply.github.com> Date: Thu, 29 Aug 2024 00:51:20 +0200 Subject: [PATCH 34/72] features.csv fix del group api version Co-authored-by: Jackson --- doc/source/features.csv | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/features.csv b/doc/source/features.csv index 47c52a80..f64da98a 100644 --- a/doc/source/features.csv +++ b/doc/source/features.csv @@ -1,7 +1,7 @@ Synapse Admin API,synadm command group / synadm command "`Account validity API `_", " `Renew account `_", -"`Delete Group API [Synapse 1.6.1] `_",:doc:`synadm.cli.group` +"`Delete Group API [Synapse 1.61] `_",:doc:`synadm.cli.group` " `Delete a local group `_",:option:`synadm group delete -h` "`Background Updates API `_", " `Status `_", From 07f7ac7dbc1ce046728795940748acc4290ed28c Mon Sep 17 00:00:00 2001 From: J0J0 Todos Date: Tue, 3 Sep 2024 06:52:58 +0200 Subject: [PATCH 35/72] Add docs scraper dependency to requirements.txt --- requirements.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/requirements.txt b/requirements.txt index 11297ecd..e249a7b2 100644 --- a/requirements.txt +++ b/requirements.txt @@ -4,3 +4,4 @@ pyyaml tabulate click-option-group>=0.5.2 dnspython +beautifulsoup4 From 0b290bab5cf275e6db6691e42d535e73db65e0ee Mon Sep 17 00:00:00 2001 From: J0J0 Todos Date: Tue, 3 Sep 2024 14:38:47 +0200 Subject: [PATCH 36/72] Fix broken media api links (due to bug in scraper) and fix "Delete a local group" link. --- doc/source/features.csv | 220 ++++++++++++++++++++-------------------- 1 file changed, 110 insertions(+), 110 deletions(-) diff --git a/doc/source/features.csv b/doc/source/features.csv index f64da98a..933524db 100644 --- a/doc/source/features.csv +++ b/doc/source/features.csv @@ -1,115 +1,115 @@ Synapse Admin API,synadm command group / synadm command -"`Account validity API `_", -" `Renew account `_", +"`Account validity API `_", +" `Renew account `_", "`Delete Group API [Synapse 1.61] `_",:doc:`synadm.cli.group` -" `Delete a local group `_",:option:`synadm group delete -h` -"`Background Updates API `_", -" `Status `_", -" `Enabled `_", -" `Run `_", -"`Event Reports API `_", -" `Show reported events `_", -" `Show details of a specific event report `_", -" `Delete a specific event report `_", -"`Experimental Features API `_", -" `Enabling/Disabling Features `_", -" `Listing Enabled Features `_", -"`Media API `_",":doc:`synadm.cli.media`, :doc:`synadm.cli.user`" -" `Querying media `_","---" -" -- `List all media in a room `_",:option:`synadm media list -r` -" -- `List all media uploaded by a user `_",:option:`synadm media list -u` :option:`synadm user media -f` -" `Quarantine media `_","---" -" -- `Quarantining media by ID `_",:option:`synadm media quarantine -i` -" -- `Remove media from quarantine by ID `_",:option:`synadm media unquarantine -i` -" -- `Quarantining media in a room `_",:option:`synadm media quarantine -r` -" -- `Quarantining all media of a user `_",:option:`synadm media quarantine -u` -" -- `Protecting media from being quarantined `_",:option:`synadm media protect MEDIA_ID` -" -- `Unprotecting media from being quarantined `_", -" `Delete local media `_","---" -" -- `Delete a specific local media `_",:option:`synadm media delete -i` -" -- `Delete local media by date or size `_",:option:`synadm media delete -d` :option:`synadm media delete --size` -" -- `Delete media uploaded by a user `_", -" `Purge Remote Media API `_",:option:`synadm media purge -d` -"`Purge History API `_",:doc:`synadm.cli.history` -" `Purge history `_",:option:`synadm history purge -i` -" `Purge status query `_",:option:`synadm history purge-status PURGE_ID` -"`Register Users API `_", -" `Shared-Secret Registration `_", -"`Registration Tokens API `_",:doc:`synadm.cli.regtok` -" `Registration token objects `_","---" -" `List all tokens `_",:option:`synadm regtok list -v` -" `Get one token `_",:option:`synadm regtok details TOKEN` -" `Create token `_",:option:`synadm regtok new -n` -" `Update token `_",:option:`synadm regtok update TOKEN` -" `Delete token `_",:option:`synadm regtok delete TOKEN` -"`Manipulate Room Membership API `_",:doc:`synadm.cli.room` -" `Edit Room Membership API `_",:option:`synadm room join ROOM_ID_OR_ALIAS` -"`Rooms API `_",:doc:`synadm.cli.room` -" `List Room API `_",:option:`synadm room list -f` -" `Room Details API `_",:option:`synadm room details ROOM_ID` -" `Room Members API `_",:option:`synadm room members ROOM_ID` -" `Room State API `_",:option:`synadm room state ROOM_ID` -" `Room Messages API `_", -" `Room Timestamp to Event API `_", -" `Block Room API `_","---" -" -- `Block or unblock a room `_",:option:`synadm room block -b` :option:`synadm room block -u` -" `Get block status `_",:option:`synadm room block-status ROOM_ID` -" `Delete Room API `_","---" -" -- `Version 1 (old version) `_",:option:`synadm room delete --v1` -" -- `Version 2 (new version) `_",:option:`synadm room delete ROOM_ID` -" -- `Status of deleting rooms `_","---" -" -- `Query by room_id `_",:option:`synadm room delete-status -r` -" -- `Query by delete_id `_",:option:`synadm room delete-status -d` -" -- `Undoing room deletions `_", -" `Make Room Admin API `_",:option:`synadm room make-admin -u` -" `Check for forward extremities `_", -" `Deleting forward extremities `_", -" `Event Context API `_", -"`Server Notices `_",:doc:`synadm.cli.notice` -" `Server Notices `_",:option:`synadm notice send TO` -"`Statistics API `_", -" `Users' media usage statistics `_", -" `Get largest rooms by size in database `_", -"`User Admin API `_",:doc:`synadm.cli.user` -" `Query User Account `_",:option:`synadm user details USER_ID` -" `Create or modify account `_",:option:`synadm user modify USER_ID` -" `List Accounts `_","---" -" -- `List Accounts (V2) `_",:option:`synadm user list -f` -" -- `List Accounts (V3) `_", -" `Query current sessions for a user `_",:option:`synadm user whois USER_ID` -" `Deactivate Account `_",:option:`synadm user deactivate USER_ID` -" `Reset password `_",:option:`synadm user password USER_ID` -" `Get whether a user is a server administrator or not `_", -" `Change whether a user is a server administrator or not `_", -" `List room memberships of a user `_",:option:`synadm user membership USER_ID` -" `Account Data `_", -" `User media `_","---" -" -- `List media uploaded by a user `_", -" -- `Delete media uploaded by a user `_",:option:`synadm user media -f` :option:`synadm media list -u` -" `Login as a user `_",:option:`synadm user login USER_ID` -" `Allow replacing master cross-signing key without... `_", -" `User devices `_","---" -" -- `List all devices `_",:option:`synadm user prune-devices --list-only` -" -- `Create a device `_", -" -- `Delete multiple devices `_",:option:`synadm user prune-devices -d` :option:`synadm user prune-devices -s` -" -- `Show a device `_",:option:`synadm user prune-devices --list-only` (-i) -" -- `Update a device `_", -" -- `Delete a device `_",:option:`synadm user prune-devices -i` -" `List all pushers `_", -" `Controlling whether a user is shadow-banned `_",:option:`synadm user shadow-ban USER_ID` :option:`synadm user shadow-ban --unban` -" `Override ratelimiting for users `_","---" -" -- `Get status of ratelimit `_", -" -- `Set ratelimit `_", -" -- `Delete ratelimit `_", -" `Check username availability `_", -" `Find a user based on their ID in an auth provider `_",:option:`synadm user 3pid ADDRESS` -" `Find a user based on their Third Party ID `_",:option:`synadm user auth-provider EXTERNAL_USER_ID` -"`Version API `_",:option:`synadm --version` -"`Federation API `_", -" `List of destinations `_", -" `Destination Details API `_", -" `Destination rooms `_", -" `Reset connection timeout `_", +" `Delete a local group `_",:option:`synadm group delete -h` +"`Background Updates API `_", +" `Status `_", +" `Enabled `_", +" `Run `_", +"`Event Reports API `_", +" `Show reported events `_", +" `Show details of a specific event report `_", +" `Delete a specific event report `_", +"`Experimental Features API `_", +" `Enabling/Disabling Features `_", +" `Listing Enabled Features `_", +"`Media API `_",":doc:`synadm.cli.media`, :doc:`synadm.cli.user`" +" `Querying media `_","---" +" -- `List all media in a room `_",:option:`synadm media list -r` +" -- `List all media uploaded by a user `_",:option:`synadm media list -u` :option:`synadm user media -f` +" `Quarantine media `_","---" +" -- `Quarantining media by ID `_",:option:`synadm media quarantine -i` +" -- `Remove media from quarantine by ID `_",:option:`synadm media unquarantine -i` +" -- `Quarantining media in a room `_",:option:`synadm media quarantine -r` +" -- `Quarantining all media of a user `_",:option:`synadm media quarantine -u` +" -- `Protecting media from being quarantined `_",:option:`synadm media protect MEDIA_ID` +" -- `Unprotecting media from being quarantined `_", +" `Delete local media `_","---" +" -- `Delete a specific local media `_",:option:`synadm media delete -i` +" -- `Delete local media by date or size `_",:option:`synadm media delete -d` :option:`synadm media delete --size` +" -- `Delete media uploaded by a user `_", +" `Purge Remote Media API `_",:option:`synadm media purge -d` +"`Purge History API `_",:doc:`synadm.cli.history` +" `Purge history `_",:option:`synadm history purge -i` +" `Purge status query `_",:option:`synadm history purge-status PURGE_ID` +"`Register Users API `_", +" `Shared-Secret Registration `_", +"`Registration Tokens API `_",:doc:`synadm.cli.regtok` +" `Registration token objects `_","---" +" `List all tokens `_",:option:`synadm regtok list -v` +" `Get one token `_",:option:`synadm regtok details TOKEN` +" `Create token `_",:option:`synadm regtok new -n` +" `Update token `_",:option:`synadm regtok update TOKEN` +" `Delete token `_",:option:`synadm regtok delete TOKEN` +"`Manipulate Room Membership API `_",:doc:`synadm.cli.room` +" `Edit Room Membership API `_",:option:`synadm room join ROOM_ID_OR_ALIAS` +"`Rooms API `_",:doc:`synadm.cli.room` +" `List Room API `_",:option:`synadm room list -f` +" `Room Details API `_",:option:`synadm room details ROOM_ID` +" `Room Members API `_",:option:`synadm room members ROOM_ID` +" `Room State API `_",:option:`synadm room state ROOM_ID` +" `Room Messages API `_", +" `Room Timestamp to Event API `_", +" `Block Room API `_","---" +" -- `Block or unblock a room `_",:option:`synadm room block -b` :option:`synadm room block -u` +" `Get block status `_",:option:`synadm room block-status ROOM_ID` +" `Delete Room API `_","---" +" -- `Version 1 (old version) `_",:option:`synadm room delete --v1` +" -- `Version 2 (new version) `_",:option:`synadm room delete ROOM_ID` +" -- `Status of deleting rooms `_","---" +" -- `Query by room_id `_",:option:`synadm room delete-status -r` +" -- `Query by delete_id `_",:option:`synadm room delete-status -d` +" -- `Undoing room deletions `_", +" `Make Room Admin API `_",:option:`synadm room make-admin -u` +" `Check for forward extremities `_", +" `Deleting forward extremities `_", +" `Event Context API `_", +"`Server Notices `_",:doc:`synadm.cli.notice` +" `Server Notices `_",:option:`synadm notice send TO` +"`Statistics API `_", +" `Users' media usage statistics `_", +" `Get largest rooms by size in database `_", +"`User Admin API `_",:doc:`synadm.cli.user` +" `Query User Account `_",:option:`synadm user details USER_ID` +" `Create or modify account `_",:option:`synadm user modify USER_ID` +" `List Accounts `_","---" +" -- `List Accounts (V2) `_",:option:`synadm user list -f` +" -- `List Accounts (V3) `_", +" `Query current sessions for a user `_",:option:`synadm user whois USER_ID` +" `Deactivate Account `_",:option:`synadm user deactivate USER_ID` +" `Reset password `_",:option:`synadm user password USER_ID` +" `Get whether a user is a server administrator or not `_", +" `Change whether a user is a server administrator or not `_", +" `List room memberships of a user `_",:option:`synadm user membership USER_ID` +" `Account Data `_", +" `User media `_","---" +" -- `List media uploaded by a user `_", +" -- `Delete media uploaded by a user `_",:option:`synadm user media -f` :option:`synadm media list -u` +" `Login as a user `_",:option:`synadm user login USER_ID` +" `Allow replacing master cross-signing key without... `_", +" `User devices `_","---" +" -- `List all devices `_",:option:`synadm user prune-devices --list-only` +" -- `Create a device `_", +" -- `Delete multiple devices `_",:option:`synadm user prune-devices -d` :option:`synadm user prune-devices -s` +" -- `Show a device `_",:option:`synadm user prune-devices --list-only` (-i) +" -- `Update a device `_", +" -- `Delete a device `_",:option:`synadm user prune-devices -i` +" `List all pushers `_", +" `Controlling whether a user is shadow-banned `_",:option:`synadm user shadow-ban USER_ID` :option:`synadm user shadow-ban --unban` +" `Override ratelimiting for users `_","---" +" -- `Get status of ratelimit `_", +" -- `Set ratelimit `_", +" -- `Delete ratelimit `_", +" `Check username availability `_", +" `Find a user based on their ID in an auth provider `_",:option:`synadm user 3pid ADDRESS` +" `Find a user based on their Third Party ID `_",:option:`synadm user auth-provider EXTERNAL_USER_ID` +"`Version API `_",:option:`synadm --version` +"`Federation API `_", +" `List of destinations `_", +" `Destination Details API `_", +" `Destination rooms `_", +" `Reset connection timeout `_", "---",:doc:`synadm.cli.config` "Any Synapse Admin API",:doc:`synadm.cli.raw` "Native Matrix API Helpers",:doc:`synadm.cli.matrix` From c1e6b3b82fc41c34805086dca91a1b9de9d90545 Mon Sep 17 00:00:00 2001 From: J0J0 Todos Date: Tue, 3 Sep 2024 14:46:43 +0200 Subject: [PATCH 37/72] Fix bug in docs scraper --- scrape_docs.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/scrape_docs.py b/scrape_docs.py index 0461e0cb..6b39aef3 100755 --- a/scrape_docs.py +++ b/scrape_docs.py @@ -35,8 +35,8 @@ def scrape(output, url): if output == 'default': print(f'{e.text} {link}') if output in ['rst', 'csv']: - parts = chapter.split('admin_api') - fulllink = f'{parts[0]}admin_api{parts[1]}{link}' + parts = chapter.split('/admin_api/') + fulllink = f'{parts[0]}/admin_api/{parts[1]}{link}' if output == 'rst': rst = f'`{e.text} <{fulllink}>`_' print(rst) From ff8e3813bd92e7ad6c89097fcb25a9b593eb0cf7 Mon Sep 17 00:00:00 2001 From: J0J0 Todos Date: Tue, 10 Sep 2024 11:15:35 +0200 Subject: [PATCH 38/72] Move scraper requirement to its own file and state how to install in the program file's comment near the very top. --- requirements.txt | 1 - scrape_docs.py | 1 + scrape_docs_requirements.txt | 1 + 3 files changed, 2 insertions(+), 1 deletion(-) create mode 100644 scrape_docs_requirements.txt diff --git a/requirements.txt b/requirements.txt index e249a7b2..11297ecd 100644 --- a/requirements.txt +++ b/requirements.txt @@ -4,4 +4,3 @@ pyyaml tabulate click-option-group>=0.5.2 dnspython -beautifulsoup4 diff --git a/scrape_docs.py b/scrape_docs.py index 6b39aef3..ae153a47 100755 --- a/scrape_docs.py +++ b/scrape_docs.py @@ -1,4 +1,5 @@ #!/usr/bin/env python +# Prerequisites: pip install -r scrape_docs_requirements.txt import click from bs4 import BeautifulSoup diff --git a/scrape_docs_requirements.txt b/scrape_docs_requirements.txt new file mode 100644 index 00000000..c1f5f713 --- /dev/null +++ b/scrape_docs_requirements.txt @@ -0,0 +1 @@ +beautifulsoup4 From fae0165c18fafe9949f33cd21233f3de23247201 Mon Sep 17 00:00:00 2001 From: J0J0 Todos Date: Tue, 10 Sep 2024 11:32:40 +0200 Subject: [PATCH 39/72] scrape_docs refactor heading tag lists definitions --- scrape_docs.py | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/scrape_docs.py b/scrape_docs.py index ae153a47..7a21d986 100755 --- a/scrape_docs.py +++ b/scrape_docs.py @@ -22,16 +22,15 @@ def scrape(output, url): apidoc = requests.get(chapter).text soup = BeautifulSoup(apidoc, 'html.parser') - elements = soup.find_all( - ['h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'a'], - ) + any_heading_tag = ['h1', 'h2', 'h3', 'h4', 'h5', 'h6'] + elements = soup.find_all([*any_heading_tag, 'a'],) for e in elements: - if e.name in ['h1', 'h2', 'h3', 'h4', 'h5', 'h6']: - if output in ['default', 'rst']: + if e.name in any_heading_tag: + if output in ['default']: print(f'{e.name}: {e.text}') if e.name == 'a': - if e.parent.name in ['h1', 'h2', 'h3', 'h4', 'h5', 'h6']: + if e.parent.name in any_heading_tag: link = e['href'] if output == 'default': print(f'{e.text} {link}') From 478317135879875d5339086ae8d38c55e13c95e5 Mon Sep 17 00:00:00 2001 From: J0J0 Todos Date: Tue, 10 Sep 2024 12:08:06 +0200 Subject: [PATCH 40/72] scrape_docs spacing magic for rst format only --- scrape_docs.py | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/scrape_docs.py b/scrape_docs.py index 7a21d986..d2566dd1 100755 --- a/scrape_docs.py +++ b/scrape_docs.py @@ -38,14 +38,22 @@ def scrape(output, url): parts = chapter.split('/admin_api/') fulllink = f'{parts[0]}/admin_api/{parts[1]}{link}' if output == 'rst': - rst = f'`{e.text} <{fulllink}>`_' + spacing = '' + for h in any_heading_tag: + if e.parent.name == h: + # h1 is no spacing (decrease by 1), + # h2 is 2 spaces, h3 is 4.... + spacing_count = int(e.parent.name[-1]) - 1 + for val in range(0, spacing_count * 2): + spacing += ' ' + rst = f'`{spacing}{e.text} <{fulllink}>`_' print(rst) # csv format also adds some spacing in front of links if output == 'csv': left_col = f'" `{e.text} <{fulllink}>`_"' print(f'{left_col},') # Final spacing only with these formats - if output in ['default', 'rst']: + if output in ['default']: print() # print(soup.prettify()) From c5b9a1bf1769d558ea0c6434667d4d89b9f9b4ea Mon Sep 17 00:00:00 2001 From: J0J0 Todos Date: Tue, 10 Sep 2024 12:15:44 +0200 Subject: [PATCH 41/72] scrape_docs spacing magic also for csv format --- scrape_docs.py | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/scrape_docs.py b/scrape_docs.py index d2566dd1..f58f4dac 100755 --- a/scrape_docs.py +++ b/scrape_docs.py @@ -37,21 +37,21 @@ def scrape(output, url): if output in ['rst', 'csv']: parts = chapter.split('/admin_api/') fulllink = f'{parts[0]}/admin_api/{parts[1]}{link}' - if output == 'rst': - spacing = '' - for h in any_heading_tag: - if e.parent.name == h: - # h1 is no spacing (decrease by 1), - # h2 is 2 spaces, h3 is 4.... - spacing_count = int(e.parent.name[-1]) - 1 - for val in range(0, spacing_count * 2): - spacing += ' ' - rst = f'`{spacing}{e.text} <{fulllink}>`_' - print(rst) + spacing = '' + for h in any_heading_tag: + if e.parent.name == h: + # h1 is no spacing (decrease by 1), + # h2 is 2 spaces, h3 is 4.... + spacing_count = int(e.parent.name[-1]) - 1 + for val in range(0, spacing_count * 2): + spacing += ' ' + rst = f'{spacing}`{e.text} <{fulllink}>`_' # csv format also adds some spacing in front of links if output == 'csv': - left_col = f'" `{e.text} <{fulllink}>`_"' + left_col = f'"{rst}"' print(f'{left_col},') + elif output == 'rst': + print(rst) # Final spacing only with these formats if output in ['default']: print() From 4a8d6b13df9639e6914549880add46fd22c31d0b Mon Sep 17 00:00:00 2001 From: J0J0 Todos Date: Tue, 10 Sep 2024 12:17:06 +0200 Subject: [PATCH 42/72] scrape_docs simplify default out condition --- scrape_docs.py | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/scrape_docs.py b/scrape_docs.py index f58f4dac..8dd07bb2 100755 --- a/scrape_docs.py +++ b/scrape_docs.py @@ -26,9 +26,8 @@ def scrape(output, url): elements = soup.find_all([*any_heading_tag, 'a'],) for e in elements: - if e.name in any_heading_tag: - if output in ['default']: - print(f'{e.name}: {e.text}') + if e.name in any_heading_tag and output == 'default': + print(f'{e.name}: {e.text}') if e.name == 'a': if e.parent.name in any_heading_tag: link = e['href'] From 800085943f52144a0aa98b40d1a8b84b74a944df Mon Sep 17 00:00:00 2001 From: J0J0 Todos Date: Tue, 10 Sep 2024 12:19:32 +0200 Subject: [PATCH 43/72] scrape_docs fix some comments --- scrape_docs.py | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/scrape_docs.py b/scrape_docs.py index 8dd07bb2..195dcb35 100755 --- a/scrape_docs.py +++ b/scrape_docs.py @@ -45,14 +45,12 @@ def scrape(output, url): for val in range(0, spacing_count * 2): spacing += ' ' rst = f'{spacing}`{e.text} <{fulllink}>`_' - # csv format also adds some spacing in front of links if output == 'csv': left_col = f'"{rst}"' print(f'{left_col},') elif output == 'rst': print(rst) - # Final spacing only with these formats - if output in ['default']: + if output == 'default': # Final spacing only with default format print() # print(soup.prettify()) From 9c762f44b4872974fddefdc8824a119c2b47c4e4 Mon Sep 17 00:00:00 2001 From: J0J0 Todos Date: Tue, 10 Sep 2024 13:02:54 +0200 Subject: [PATCH 44/72] scrape_docs output formats naming and improvements Rename "default" output format to "debug", make it slightly more useful and make "csv" the new default output format. --- scrape_docs.py | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/scrape_docs.py b/scrape_docs.py index 195dcb35..1f0447b0 100755 --- a/scrape_docs.py +++ b/scrape_docs.py @@ -8,8 +8,8 @@ @click.command() @click.option( - '--output', '-o', default='default', - type=click.Choice(['default', 'rst', 'csv']), show_choices=True, + '--output', '-o', default='csv', + type=click.Choice(['debug', 'rst', 'csv']), show_choices=True, help='''Output format "default" prints human readable on shell, "csv" is a two-column comma separated value format.''') @click.argument('URL') @@ -26,13 +26,13 @@ def scrape(output, url): elements = soup.find_all([*any_heading_tag, 'a'],) for e in elements: - if e.name in any_heading_tag and output == 'default': + if e.name in any_heading_tag and output == 'debug': print(f'{e.name}: {e.text}') if e.name == 'a': if e.parent.name in any_heading_tag: link = e['href'] - if output == 'default': - print(f'{e.text} {link}') + if output == 'debug': + print(f'Element text:\t{e.text}\nLink/Anchor:\t{link}') if output in ['rst', 'csv']: parts = chapter.split('/admin_api/') fulllink = f'{parts[0]}/admin_api/{parts[1]}{link}' @@ -50,7 +50,7 @@ def scrape(output, url): print(f'{left_col},') elif output == 'rst': print(rst) - if output == 'default': # Final spacing only with default format + if output == 'debug': # Final spacing only with debug format print() # print(soup.prettify()) From e58b6aa826aaaa7cd50a6d364284cc011024ae2a Mon Sep 17 00:00:00 2001 From: J0J0 Todos Date: Tue, 10 Sep 2024 13:22:18 +0200 Subject: [PATCH 45/72] scrap_docs improve online help wording --- scrape_docs.py | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) diff --git a/scrape_docs.py b/scrape_docs.py index 1f0447b0..766b3d20 100755 --- a/scrape_docs.py +++ b/scrape_docs.py @@ -10,14 +10,22 @@ @click.option( '--output', '-o', default='csv', type=click.Choice(['debug', 'rst', 'csv']), show_choices=True, - help='''Output format "default" prints human readable on shell, "csv" is a - two-column comma separated value format.''') + help='''Output format "debug" prints headline level, headline text and the + scraped link/anchor; "rst" gives a restructuredText formatted hyperlink + including space-indentation according to headline levels; "csv" is a + two-column comma separated value format that includes the results of "rst" + as the left column's contents. Additionally "csv" adds a restructuredText + formatted headline above the table''') @click.argument('URL') def scrape(output, url): '''Scrape one chapter of Admin API docs and spit out in various formats. URL is the address of the Synapse Admin API docs chapter. For example: - https://element-hq.github.io/synapse/develop/admin_api/rooms.html''' + https://element-hq.github.io/synapse/latest/admin_api/rooms.html + + The default output format is "csv", which gives a two column CSV table + containing restructuredText formatted hyperlinks and a headline. + ''' chapter = url apidoc = requests.get(chapter).text soup = BeautifulSoup(apidoc, 'html.parser') From 14bb4d010b134fedc07d7702f83bf37dd25cc65d Mon Sep 17 00:00:00 2001 From: J0J0 Todos Date: Tue, 10 Sep 2024 13:38:27 +0200 Subject: [PATCH 46/72] scrape_docs add headline output to csv format --- scrape_docs.py | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/scrape_docs.py b/scrape_docs.py index 766b3d20..27f64286 100755 --- a/scrape_docs.py +++ b/scrape_docs.py @@ -33,6 +33,10 @@ def scrape(output, url): any_heading_tag = ['h1', 'h2', 'h3', 'h4', 'h5', 'h6'] elements = soup.find_all([*any_heading_tag, 'a'],) + if output == 'csv': + print('Change this headline as required') + print('================================\n') + for e in elements: if e.name in any_heading_tag and output == 'debug': print(f'{e.name}: {e.text}') From e43605ceba892d0aa2f65657ab086f1e5fda22f8 Mon Sep 17 00:00:00 2001 From: J0J0 Todos Date: Tue, 10 Sep 2024 14:14:22 +0200 Subject: [PATCH 47/72] scrape_docs add column headlines --- scrape_docs.py | 1 + 1 file changed, 1 insertion(+) diff --git a/scrape_docs.py b/scrape_docs.py index 27f64286..26f4d698 100755 --- a/scrape_docs.py +++ b/scrape_docs.py @@ -36,6 +36,7 @@ def scrape(output, url): if output == 'csv': print('Change this headline as required') print('================================\n') + print('"Synapse Admin API","synadm command(s)"') for e in elements: if e.name in any_heading_tag and output == 'debug': From 511637533d712cc8830c11e47e04e6d9b51c259e Mon Sep 17 00:00:00 2001 From: J0J0 Todos Date: Tue, 10 Sep 2024 15:00:50 +0200 Subject: [PATCH 48/72] features.csv split into multiple files part 1 only add headlines and spacing, all into original file. --- doc/source/features.csv | 256 +++++++++++++++++++++++++--------------- 1 file changed, 159 insertions(+), 97 deletions(-) diff --git a/doc/source/features.csv b/doc/source/features.csv index 933524db..f29d740a 100644 --- a/doc/source/features.csv +++ b/doc/source/features.csv @@ -1,116 +1,178 @@ -Synapse Admin API,synadm command group / synadm command -"`Account validity API `_", -" `Renew account `_", -"`Delete Group API [Synapse 1.61] `_",:doc:`synadm.cli.group` -" `Delete a local group `_",:option:`synadm group delete -h` -"`Background Updates API `_", -" `Status `_", -" `Enabled `_", -" `Run `_", -"`Event Reports API `_", +Account validity API +==================== +"Synapse Admin API","synadm command(s)" +"`Renew account `_", + + +Delete Group API +================ +"Synapse Admin API","synadm command(s)" +"`Delete a local group `_",:option:`synadm group delete -h` + + +Background Updates API +====================== +"Synapse Admin API","synadm command(s)" +"`Status `_", +"`Enabled `_", +"`Run `_", + + +Event Reports API +================= +"Synapse Admin API","synadm command(s)" " `Show reported events `_", " `Show details of a specific event report `_", " `Delete a specific event report `_", "`Experimental Features API `_", " `Enabling/Disabling Features `_", " `Listing Enabled Features `_", -"`Media API `_",":doc:`synadm.cli.media`, :doc:`synadm.cli.user`" -" `Querying media `_","---" -" -- `List all media in a room `_",:option:`synadm media list -r` -" -- `List all media uploaded by a user `_",:option:`synadm media list -u` :option:`synadm user media -f` -" `Quarantine media `_","---" -" -- `Quarantining media by ID `_",:option:`synadm media quarantine -i` -" -- `Remove media from quarantine by ID `_",:option:`synadm media unquarantine -i` -" -- `Quarantining media in a room `_",:option:`synadm media quarantine -r` -" -- `Quarantining all media of a user `_",:option:`synadm media quarantine -u` -" -- `Protecting media from being quarantined `_",:option:`synadm media protect MEDIA_ID` -" -- `Unprotecting media from being quarantined `_", -" `Delete local media `_","---" -" -- `Delete a specific local media `_",:option:`synadm media delete -i` -" -- `Delete local media by date or size `_",:option:`synadm media delete -d` :option:`synadm media delete --size` -" -- `Delete media uploaded by a user `_", -" `Purge Remote Media API `_",:option:`synadm media purge -d` -"`Purge History API `_",:doc:`synadm.cli.history` -" `Purge history `_",:option:`synadm history purge -i` -" `Purge status query `_",:option:`synadm history purge-status PURGE_ID` -"`Register Users API `_", -" `Shared-Secret Registration `_", -"`Registration Tokens API `_",:doc:`synadm.cli.regtok` -" `Registration token objects `_","---" -" `List all tokens `_",:option:`synadm regtok list -v` -" `Get one token `_",:option:`synadm regtok details TOKEN` -" `Create token `_",:option:`synadm regtok new -n` -" `Update token `_",:option:`synadm regtok update TOKEN` -" `Delete token `_",:option:`synadm regtok delete TOKEN` -"`Manipulate Room Membership API `_",:doc:`synadm.cli.room` -" `Edit Room Membership API `_",:option:`synadm room join ROOM_ID_OR_ALIAS` -"`Rooms API `_",:doc:`synadm.cli.room` -" `List Room API `_",:option:`synadm room list -f` -" `Room Details API `_",:option:`synadm room details ROOM_ID` -" `Room Members API `_",:option:`synadm room members ROOM_ID` -" `Room State API `_",:option:`synadm room state ROOM_ID` -" `Room Messages API `_", -" `Room Timestamp to Event API `_", -" `Block Room API `_","---" -" -- `Block or unblock a room `_",:option:`synadm room block -b` :option:`synadm room block -u` + + +Media API +========= +"Synapse Admin API","synadm command(s)" +"`Querying media `_","---" +" `List all media in a room `_",:option:`synadm media list -r` +" `List all media uploaded by a user `_",:option:`synadm media list -u` :option:`synadm user media -f` +"`Quarantine media `_","---" +" `Quarantining media by ID `_",:option:`synadm media quarantine -i` +" `Remove media from quarantine by ID `_",:option:`synadm media unquarantine -i` +" `Quarantining media in a room `_",:option:`synadm media quarantine -r` +" `Quarantining all media of a user `_",:option:`synadm media quarantine -u` +" `Protecting media from being quarantined `_",:option:`synadm media protect MEDIA_ID` +" `Unprotecting media from being quarantined `_", +"`Delete local media `_","---" +" `Delete a specific local media `_",:option:`synadm media delete -i` +" `Delete local media by date or size `_",:option:`synadm media delete -d` :option:`synadm media delete --size` +" `Delete media uploaded by a user `_", +"`Purge Remote Media API `_",:option:`synadm media purge -d` + + +Purge History API +================= +"Synapse Admin API","synadm command(s)" +"`Purge history `_",:option:`synadm history purge -i` +"`Purge status query `_",:option:`synadm history purge-status PURGE_ID` + + +Register Users API +================== +"`Shared-Secret Registration `_", + + +Registration Tokens API +======================= +"Synapse Admin API","synadm command(s)" +"`Registration token objects `_","---" +"`List all tokens `_",:option:`synadm regtok list -v` +"`Get one token `_",:option:`synadm regtok details TOKEN` +"`Create token `_",:option:`synadm regtok new -n` +"`Update token `_",:option:`synadm regtok update TOKEN` +"`Delete token `_",:option:`synadm regtok delete TOKEN` + + +Manipulate Room Mamebership API +=============================== +"Synapse Admin API","synadm command(s)" +"`Edit Room Membership API `_",:option:`synadm room join ROOM_ID_OR_ALIAS` + + +Rooms API +========= +"Synapse Admin API","synadm command(s)" +"`List Room API `_",:option:`synadm room list -f` +"`Room Details API `_",:option:`synadm room details ROOM_ID` +"`Room Members API `_",:option:`synadm room members ROOM_ID` +"`Room State API `_",:option:`synadm room state ROOM_ID` +"`Room Messages API `_", +"`Room Timestamp to Event API `_", +"`Block Room API `_","---" +" `Block or unblock a room `_",:option:`synadm room block -b` :option:`synadm room block -u` " `Get block status `_",:option:`synadm room block-status ROOM_ID` -" `Delete Room API `_","---" -" -- `Version 1 (old version) `_",:option:`synadm room delete --v1` -" -- `Version 2 (new version) `_",:option:`synadm room delete ROOM_ID` -" -- `Status of deleting rooms `_","---" -" -- `Query by room_id `_",:option:`synadm room delete-status -r` -" -- `Query by delete_id `_",:option:`synadm room delete-status -d` -" -- `Undoing room deletions `_", -" `Make Room Admin API `_",:option:`synadm room make-admin -u` +"`Delete Room API `_","---" +" `Version 1 (old version) `_",:option:`synadm room delete --v1` +" `Version 2 (new version) `_",:option:`synadm room delete ROOM_ID` +" `Status of deleting rooms `_","---" +" `Query by room_id `_",:option:`synadm room delete-status -r` +" `Query by delete_id `_",:option:`synadm room delete-status -d` +" `Undoing room deletions `_", +"`Make Room Admin API `_",:option:`synadm room make-admin -u` +"`Forward Extremities Admin API `_", " `Check for forward extremities `_", " `Deleting forward extremities `_", -" `Event Context API `_", -"`Server Notices `_",:doc:`synadm.cli.notice` -" `Server Notices `_",:option:`synadm notice send TO` -"`Statistics API `_", -" `Users' media usage statistics `_", -" `Get largest rooms by size in database `_", -"`User Admin API `_",:doc:`synadm.cli.user` -" `Query User Account `_",:option:`synadm user details USER_ID` -" `Create or modify account `_",:option:`synadm user modify USER_ID` -" `List Accounts `_","---" -" -- `List Accounts (V2) `_",:option:`synadm user list -f` -" -- `List Accounts (V3) `_", -" `Query current sessions for a user `_",:option:`synadm user whois USER_ID` -" `Deactivate Account `_",:option:`synadm user deactivate USER_ID` -" `Reset password `_",:option:`synadm user password USER_ID` -" `Get whether a user is a server administrator or not `_", -" `Change whether a user is a server administrator or not `_", -" `List room memberships of a user `_",:option:`synadm user membership USER_ID` -" `Account Data `_", -" `User media `_","---" -" -- `List media uploaded by a user `_", -" -- `Delete media uploaded by a user `_",:option:`synadm user media -f` :option:`synadm media list -u` -" `Login as a user `_",:option:`synadm user login USER_ID` -" `Allow replacing master cross-signing key without... `_", -" `User devices `_","---" -" -- `List all devices `_",:option:`synadm user prune-devices --list-only` -" -- `Create a device `_", -" -- `Delete multiple devices `_",:option:`synadm user prune-devices -d` :option:`synadm user prune-devices -s` -" -- `Show a device `_",:option:`synadm user prune-devices --list-only` (-i) -" -- `Update a device `_", -" -- `Delete a device `_",:option:`synadm user prune-devices -i` -" `List all pushers `_", -" `Controlling whether a user is shadow-banned `_",:option:`synadm user shadow-ban USER_ID` :option:`synadm user shadow-ban --unban` -" `Override ratelimiting for users `_","---" -" -- `Get status of ratelimit `_", -" -- `Set ratelimit `_", -" -- `Delete ratelimit `_", -" `Check username availability `_", -" `Find a user based on their ID in an auth provider `_",:option:`synadm user 3pid ADDRESS` -" `Find a user based on their Third Party ID `_",:option:`synadm user auth-provider EXTERNAL_USER_ID` +"`Event Context API `_", + + +Server Notices API +================== +"Synapse Admin API","synadm command(s)" +"`Server Notices `_",:option:`synadm notice send TO` + +Statistics +========== +"`Users' media usage statistics `_", +"`Get largest rooms by size in database `_", + + +User Admin API +============== +"Synapse Admin API","synadm command(s)" +"`Query User Account `_",:option:`synadm user details USER_ID` +"`Create or modify account `_",:option:`synadm user modify USER_ID` +"`List Accounts `_","---" +" `List Accounts (V2) `_",:option:`synadm user list -f` +" `List Accounts (V3) `_", +"`Query current sessions for a user `_",:option:`synadm user whois USER_ID` +"`Deactivate Account `_",:option:`synadm user deactivate USER_ID` +"`Reset password `_",:option:`synadm user password USER_ID` +"`Get whether a user is a server administrator or not `_", +"`Change whether a user is a server administrator or not `_", +"`List room memberships of a user `_",:option:`synadm user membership USER_ID` +"`Account Data `_", +"`User media `_","---" +" `List media uploaded by a user `_", +" `Delete media uploaded by a user `_",:option:`synadm user media -f` :option:`synadm media list -u` +"`Login as a user `_",:option:`synadm user login USER_ID` +"`Allow replacing master cross-signing key without... `_", +"`User devices `_","---" +" `List all devices `_",:option:`synadm user prune-devices --list-only` +" `Create a device `_", +" `Delete multiple devices `_",:option:`synadm user prune-devices -d` :option:`synadm user prune-devices -s` +" `Show a device `_",:option:`synadm user prune-devices --list-only` (-i) +" `Update a device `_", +" `Delete a device `_",:option:`synadm user prune-devices -i` +"`List all pushers `_", +"`Controlling whether a user is shadow-banned `_",:option:`synadm user shadow-ban USER_ID` :option:`synadm user shadow-ban --unban` +"`Override ratelimiting for users `_","---" +" `Get status of ratelimit `_", +" `Set ratelimit `_", +" `Delete ratelimit `_", +"`Check username availability `_", +"`Find a user based on their ID in an auth provider `_",:option:`synadm user 3pid ADDRESS` +"`Find a user based on their Third Party ID `_",:option:`synadm user auth-provider EXTERNAL_USER_ID` + + +Version API +=========== +"Synapse Admin API","synadm command(s)" "`Version API `_",:option:`synadm --version` + + +Federation API +============== +"Synapse Admin API","synadm command(s)" "`Federation API `_", " `List of destinations `_", " `Destination Details API `_", " `Destination rooms `_", " `Reset connection timeout `_", "---",:doc:`synadm.cli.config` + + +Miscellaneous +============= +"Synapse Admin API","synadm command(s)" "Any Synapse Admin API",:doc:`synadm.cli.raw` "Native Matrix API Helpers",:doc:`synadm.cli.matrix` " Matrix User Login",:option:`synadm matrix login USER_ID` From 0e9eaa784ac9917afa1938bbd766911336a25c33 Mon Sep 17 00:00:00 2001 From: J0J0 Todos Date: Tue, 10 Sep 2024 15:11:25 +0200 Subject: [PATCH 49/72] features.csv split into multiple files part 2 proof of concept with 2 chapters and separate files... --- doc/source/features.rst | 15 ++++++++++++++- doc/source/features_account_validity.csv | 2 ++ doc/source/features_delete_group.csv | 2 ++ 3 files changed, 18 insertions(+), 1 deletion(-) create mode 100644 doc/source/features_account_validity.csv create mode 100644 doc/source/features_delete_group.csv diff --git a/doc/source/features.rst b/doc/source/features.rst index a4b7bad1..65ae7a63 100644 --- a/doc/source/features.rst +++ b/doc/source/features.rst @@ -7,12 +7,25 @@ Below table shows which Synapse Admin APIs are used by their corresponding in ``synadm`` for an API that is already tracked here, file a `feature request issue`_ or even better, a `pull request`_ implementing the feature. +Account Validity API +-------------------- + +.. csv-table:: Admin API vs Command Overview + :file: features_account_validity.csv + :header-rows: 1 + :class: longtable + :widths: 1 1 + +Delete Group API +---------------- + .. csv-table:: Admin API vs Command Overview - :file: features.csv + :file: features_delete_group.csv :header-rows: 1 :class: longtable :widths: 1 1 + .. _features.csv: https://github.com/JOJ0/synadm/tree/master/doc/source/features.csv .. _feature request issue: diff --git a/doc/source/features_account_validity.csv b/doc/source/features_account_validity.csv new file mode 100644 index 00000000..31b07b59 --- /dev/null +++ b/doc/source/features_account_validity.csv @@ -0,0 +1,2 @@ +"Synapse Admin API","synadm command(s)" +"`Renew account `_", \ No newline at end of file diff --git a/doc/source/features_delete_group.csv b/doc/source/features_delete_group.csv new file mode 100644 index 00000000..6db76e5f --- /dev/null +++ b/doc/source/features_delete_group.csv @@ -0,0 +1,2 @@ +"Synapse Admin API","synadm command(s)" +"`Delete a local group `_",:option:`synadm group delete -h` \ No newline at end of file From 5dc2183a2fa18c43555596c538b9f61af8fd7876 Mon Sep 17 00:00:00 2001 From: J0J0 Todos Date: Wed, 11 Sep 2024 15:21:10 +0200 Subject: [PATCH 50/72] Fixes in soon unused features.csv --- doc/source/features.csv | 26 ++++++++++++++------------ 1 file changed, 14 insertions(+), 12 deletions(-) diff --git a/doc/source/features.csv b/doc/source/features.csv index f29d740a..d953ec4a 100644 --- a/doc/source/features.csv +++ b/doc/source/features.csv @@ -21,12 +21,15 @@ Background Updates API Event Reports API ================= "Synapse Admin API","synadm command(s)" -" `Show reported events `_", -" `Show details of a specific event report `_", -" `Delete a specific event report `_", -"`Experimental Features API `_", -" `Enabling/Disabling Features `_", -" `Listing Enabled Features `_", +"`Show reported events `_", +"`Show details of a specific event report `_", +"`Delete a specific event report `_", + + +Experimental Features API +========================= +"`Enabling/Disabling Features `_", +"`Listing Enabled Features `_", Media API @@ -162,17 +165,16 @@ Version API Federation API ============== "Synapse Admin API","synadm command(s)" -"`Federation API `_", -" `List of destinations `_", -" `Destination Details API `_", -" `Destination rooms `_", -" `Reset connection timeout `_", -"---",:doc:`synadm.cli.config` +"`List of destinations `_", +"`Destination Details API `_", +"`Destination rooms `_", +"`Reset connection timeout `_", Miscellaneous ============= "Synapse Admin API","synadm command(s)" +"---",:doc:`synadm.cli.config` "Any Synapse Admin API",:doc:`synadm.cli.raw` "Native Matrix API Helpers",:doc:`synadm.cli.matrix` " Matrix User Login",:option:`synadm matrix login USER_ID` From b92efa933931892b712a60fad57edd0bad98990d Mon Sep 17 00:00:00 2001 From: J0J0 Todos Date: Wed, 11 Sep 2024 15:38:52 +0200 Subject: [PATCH 51/72] Separate table/csv-file for each Synapse Admin docs chapter --- doc/source/features.rst | 130 ++++++++++++++++-- doc/source/features_account_validity.csv | 3 +- doc/source/features_background_updates.csv | 3 + doc/source/features_delete_group.csv | 3 +- doc/source/features_event_reports.csv | 3 + doc/source/features_experimental_features.csv | 2 + doc/source/features_federation.csv | 4 + .../features_manipulate_room_membership.csv | 1 + doc/source/features_media.csv | 15 ++ doc/source/features_purge_history.csv | 2 + doc/source/features_register_users.csv | 1 + doc/source/features_registration_tokens.csv | 6 + doc/source/features_rooms.csv | 21 +++ doc/source/features_server_notices.csv | 1 + doc/source/features_server_version.csv | 1 + doc/source/features_statistics.csv | 2 + doc/source/features_users.csv | 33 +++++ 17 files changed, 217 insertions(+), 14 deletions(-) create mode 100644 doc/source/features_background_updates.csv create mode 100644 doc/source/features_event_reports.csv create mode 100644 doc/source/features_experimental_features.csv create mode 100644 doc/source/features_federation.csv create mode 100644 doc/source/features_manipulate_room_membership.csv create mode 100644 doc/source/features_media.csv create mode 100644 doc/source/features_purge_history.csv create mode 100644 doc/source/features_register_users.csv create mode 100644 doc/source/features_registration_tokens.csv create mode 100644 doc/source/features_rooms.csv create mode 100644 doc/source/features_server_notices.csv create mode 100644 doc/source/features_server_version.csv create mode 100644 doc/source/features_statistics.csv create mode 100644 doc/source/features_users.csv diff --git a/doc/source/features.rst b/doc/source/features.rst index 65ae7a63..d1709e53 100644 --- a/doc/source/features.rst +++ b/doc/source/features.rst @@ -7,22 +7,132 @@ Below table shows which Synapse Admin APIs are used by their corresponding in ``synadm`` for an API that is already tracked here, file a `feature request issue`_ or even better, a `pull request`_ implementing the feature. -Account Validity API --------------------- +Account Validity +---------------- -.. csv-table:: Admin API vs Command Overview +.. csv-table:: :file: features_account_validity.csv - :header-rows: 1 - :class: longtable + :header: "Synapse Admin API","synadm command(s)" :widths: 1 1 -Delete Group API ----------------- +Background Updates +------------------ + +.. csv-table:: + :file: features_background_updates.csv + :header: "Synapse Admin API","synadm command(s)" + :widths: 1 1 + +Delete Group +------------ -.. csv-table:: Admin API vs Command Overview +.. csv-table:: :file: features_delete_group.csv - :header-rows: 1 - :class: longtable + :header: "Synapse Admin API","synadm command(s)" + :widths: 1 1 + +Event Reports +------------- + +.. csv-table:: + :file: features_event_reports.csv + :header: "Synapse Admin API","synadm command(s)" + :widths: 1 1 + +Experimental Features +--------------------- + +.. csv-table:: + :file: features_experimental_features.csv + :header: "Synapse Admin API","synadm command(s)" + :widths: 1 1 + +Media +----- + +.. csv-table:: + :file: features_media.csv + :header: "Synapse Admin API","synadm command(s)" + :widths: 1 1 + +Purge History +------------- + +.. csv-table:: + :file: features_purge_history.csv + :header: "Synapse Admin API","synadm command(s)" + :widths: 1 1 + +Register Users +-------------- + +.. csv-table:: + :file: features_register_users.csv + :header: "Synapse Admin API","synadm command(s)" + :widths: 1 1 + +Registration Tokens +------------------- + +.. csv-table:: + :file: features_registration_tokens.csv + :header: "Synapse Admin API","synadm command(s)" + :widths: 1 1 + +Manipulate Room Membership +-------------------------- + +.. csv-table:: + :file: features_manipulate_room_membership.csv + :header: "Synapse Admin API","synadm command(s)" + :widths: 1 1 + +Rooms +----- + +.. csv-table:: + :file: features_rooms.csv + :header: "Synapse Admin API","synadm command(s)" + :widths: 1 1 + +Server Notices +-------------- + +.. csv-table:: + :file: features_server_notices.csv + :header: "Synapse Admin API","synadm command(s)" + :widths: 1 1 + +Statistics +---------- + +.. csv-table:: + :file: features_statistics.csv + :header: "Synapse Admin API","synadm command(s)" + :widths: 1 1 + +Users +----- + +.. csv-table:: + :file: features_users.csv + :header: "Synapse Admin API","synadm command(s)" + :widths: 1 1 + +Server Version +-------------- + +.. csv-table:: + :file: features_server_version.csv + :header: "Synapse Admin API","synadm command(s)" + :widths: 1 1 + +Federation +---------- + +.. csv-table:: + :file: features_federation.csv + :header: "Synapse Admin API","synadm command(s)" :widths: 1 1 diff --git a/doc/source/features_account_validity.csv b/doc/source/features_account_validity.csv index 31b07b59..c56288f1 100644 --- a/doc/source/features_account_validity.csv +++ b/doc/source/features_account_validity.csv @@ -1,2 +1 @@ -"Synapse Admin API","synadm command(s)" -"`Renew account `_", \ No newline at end of file +"`Renew account `_", diff --git a/doc/source/features_background_updates.csv b/doc/source/features_background_updates.csv new file mode 100644 index 00000000..076346bc --- /dev/null +++ b/doc/source/features_background_updates.csv @@ -0,0 +1,3 @@ +"`Status `_", +"`Enabled `_", +"`Run `_", diff --git a/doc/source/features_delete_group.csv b/doc/source/features_delete_group.csv index 6db76e5f..83415f71 100644 --- a/doc/source/features_delete_group.csv +++ b/doc/source/features_delete_group.csv @@ -1,2 +1 @@ -"Synapse Admin API","synadm command(s)" -"`Delete a local group `_",:option:`synadm group delete -h` \ No newline at end of file +"`Delete a local group `_",:option:`synadm group delete GROUP_ID` diff --git a/doc/source/features_event_reports.csv b/doc/source/features_event_reports.csv new file mode 100644 index 00000000..427effc6 --- /dev/null +++ b/doc/source/features_event_reports.csv @@ -0,0 +1,3 @@ +"`Show reported events `_", +"`Show details of a specific event report `_", +"`Delete a specific event report `_", diff --git a/doc/source/features_experimental_features.csv b/doc/source/features_experimental_features.csv new file mode 100644 index 00000000..3c9f6050 --- /dev/null +++ b/doc/source/features_experimental_features.csv @@ -0,0 +1,2 @@ +"`Enabling/Disabling Features `_", +"`Listing Enabled Features `_", diff --git a/doc/source/features_federation.csv b/doc/source/features_federation.csv new file mode 100644 index 00000000..d5bab9bd --- /dev/null +++ b/doc/source/features_federation.csv @@ -0,0 +1,4 @@ +"`List of destinations `_", +"`Destination Details API `_", +"`Destination rooms `_", +"`Reset connection timeout `_", diff --git a/doc/source/features_manipulate_room_membership.csv b/doc/source/features_manipulate_room_membership.csv new file mode 100644 index 00000000..599f5563 --- /dev/null +++ b/doc/source/features_manipulate_room_membership.csv @@ -0,0 +1 @@ +"`Edit Room Membership API `_",:option:`synadm room join ROOM_ID_OR_ALIAS` diff --git a/doc/source/features_media.csv b/doc/source/features_media.csv new file mode 100644 index 00000000..45a803d3 --- /dev/null +++ b/doc/source/features_media.csv @@ -0,0 +1,15 @@ +"`Querying media `_","---" +" `List all media in a room `_",:option:`synadm media list -r` +" `List all media uploaded by a user `_",:option:`synadm media list -u` :option:`synadm user media -f` +"`Quarantine media `_","---" +" `Quarantining media by ID `_",:option:`synadm media quarantine -i` +" `Remove media from quarantine by ID `_",:option:`synadm media unquarantine -i` +" `Quarantining media in a room `_",:option:`synadm media quarantine -r` +" `Quarantining all media of a user `_",:option:`synadm media quarantine -u` +" `Protecting media from being quarantined `_",:option:`synadm media protect MEDIA_ID` +" `Unprotecting media from being quarantined `_", +"`Delete local media `_","---" +" `Delete a specific local media `_",:option:`synadm media delete -i` +" `Delete local media by date or size `_",:option:`synadm media delete -d` :option:`synadm media delete --size` +" `Delete media uploaded by a user `_", +"`Purge Remote Media API `_",:option:`synadm media purge -d` diff --git a/doc/source/features_purge_history.csv b/doc/source/features_purge_history.csv new file mode 100644 index 00000000..0ab0f26e --- /dev/null +++ b/doc/source/features_purge_history.csv @@ -0,0 +1,2 @@ +"`Purge history `_",:option:`synadm history purge -i` +"`Purge status query `_",:option:`synadm history purge-status PURGE_ID` diff --git a/doc/source/features_register_users.csv b/doc/source/features_register_users.csv new file mode 100644 index 00000000..42e9838d --- /dev/null +++ b/doc/source/features_register_users.csv @@ -0,0 +1 @@ +"`Shared-Secret Registration `_", diff --git a/doc/source/features_registration_tokens.csv b/doc/source/features_registration_tokens.csv new file mode 100644 index 00000000..b0050692 --- /dev/null +++ b/doc/source/features_registration_tokens.csv @@ -0,0 +1,6 @@ +"`Registration token objects `_","---" +"`List all tokens `_",:option:`synadm regtok list -v` +"`Get one token `_",:option:`synadm regtok details TOKEN` +"`Create token `_",:option:`synadm regtok new -n` +"`Update token `_",:option:`synadm regtok update TOKEN` +"`Delete token `_",:option:`synadm regtok delete TOKEN` diff --git a/doc/source/features_rooms.csv b/doc/source/features_rooms.csv new file mode 100644 index 00000000..d3b99586 --- /dev/null +++ b/doc/source/features_rooms.csv @@ -0,0 +1,21 @@ +"`List Room API `_",:option:`synadm room list -f` +"`Room Details API `_",:option:`synadm room details ROOM_ID` +"`Room Members API `_",:option:`synadm room members ROOM_ID` +"`Room State API `_",:option:`synadm room state ROOM_ID` +"`Room Messages API `_", +"`Room Timestamp to Event API `_", +"`Block Room API `_","---" +" `Block or unblock a room `_",:option:`synadm room block -b` :option:`synadm room block -u` +" `Get block status `_",:option:`synadm room block-status ROOM_ID` +"`Delete Room API `_","---" +" `Version 1 (old version) `_",:option:`synadm room delete --v1` +" `Version 2 (new version) `_",:option:`synadm room delete ROOM_ID` +" `Status of deleting rooms `_","---" +" `Query by room_id `_",:option:`synadm room delete-status -r` +" `Query by delete_id `_",:option:`synadm room delete-status -d` +" `Undoing room deletions `_", +"`Make Room Admin API `_",:option:`synadm room make-admin -u` +"`Forward Extremities Admin API `_", +" `Check for forward extremities `_", +" `Deleting forward extremities `_", +"`Event Context API `_", diff --git a/doc/source/features_server_notices.csv b/doc/source/features_server_notices.csv new file mode 100644 index 00000000..415a6315 --- /dev/null +++ b/doc/source/features_server_notices.csv @@ -0,0 +1 @@ +"`Server Notices `_",:option:`synadm notice send TO` diff --git a/doc/source/features_server_version.csv b/doc/source/features_server_version.csv new file mode 100644 index 00000000..ddc6daf4 --- /dev/null +++ b/doc/source/features_server_version.csv @@ -0,0 +1 @@ +"`Version API `_",:option:`synadm version` diff --git a/doc/source/features_statistics.csv b/doc/source/features_statistics.csv new file mode 100644 index 00000000..6ed4f3f8 --- /dev/null +++ b/doc/source/features_statistics.csv @@ -0,0 +1,2 @@ +"`Users' media usage statistics `_", +"`Get largest rooms by size in database `_", diff --git a/doc/source/features_users.csv b/doc/source/features_users.csv new file mode 100644 index 00000000..bafda52b --- /dev/null +++ b/doc/source/features_users.csv @@ -0,0 +1,33 @@ +"`Query User Account `_",:option:`synadm user details USER_ID` +"`Create or modify account `_",:option:`synadm user modify USER_ID` +"`List Accounts `_","---" +" `List Accounts (V2) `_",:option:`synadm user list -f` +" `List Accounts (V3) `_", +"`Query current sessions for a user `_",:option:`synadm user whois USER_ID` +"`Deactivate Account `_",:option:`synadm user deactivate USER_ID` +"`Reset password `_",:option:`synadm user password USER_ID` +"`Get whether a user is a server administrator or not `_", +"`Change whether a user is a server administrator or not `_", +"`List room memberships of a user `_",:option:`synadm user membership USER_ID` +"`Account Data `_", +"`User media `_","---" +" `List media uploaded by a user `_", +" `Delete media uploaded by a user `_",:option:`synadm user media -f` :option:`synadm media list -u` +"`Login as a user `_",:option:`synadm user login USER_ID` +"`Allow replacing master cross-signing key without... `_", +"`User devices `_","---" +" `List all devices `_",:option:`synadm user prune-devices --list-only` +" `Create a device `_", +" `Delete multiple devices `_",:option:`synadm user prune-devices -d` :option:`synadm user prune-devices -s` +" `Show a device `_",:option:`synadm user prune-devices --list-only` (-i) +" `Update a device `_", +" `Delete a device `_",:option:`synadm user prune-devices -i` +"`List all pushers `_", +"`Controlling whether a user is shadow-banned `_",:option:`synadm user shadow-ban USER_ID` :option:`synadm user shadow-ban --unban` +"`Override ratelimiting for users `_","---" +" `Get status of ratelimit `_", +" `Set ratelimit `_", +" `Delete ratelimit `_", +"`Check username availability `_", +"`Find a user based on their ID in an auth provider `_",:option:`synadm user 3pid ADDRESS` +"`Find a user based on their Third Party ID `_",:option:`synadm user auth-provider EXTERNAL_USER_ID` From cbdca547dc5f204b32851fb026f6441142edb237 Mon Sep 17 00:00:00 2001 From: J0J0 Todos Date: Wed, 11 Sep 2024 16:11:00 +0200 Subject: [PATCH 52/72] Reword features.rst intro text --- doc/source/features.rst | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/doc/source/features.rst b/doc/source/features.rst index d1709e53..6d902350 100644 --- a/doc/source/features.rst +++ b/doc/source/features.rst @@ -1,11 +1,9 @@ Synapse Admin API Coverage ========================== -Below table shows which Synapse Admin APIs are used by their corresponding -``synadm`` commands. To add a newly released or otherwise missing API, edit -`features.csv`_ and submit a `pull request`_. If you happen to miss a feature -in ``synadm`` for an API that is already tracked here, file a `feature request -issue`_ or even better, a `pull request`_ implementing the feature. +The tables below show which Synapse Admin APIs are used by their corresponding ``synadm`` commands. +The left column's entries link to the official Synapse Admin API documentation, the right column's entries point to the ``synadm`` CLI reference. +To add missing entries to a table edit one of the CSV files in our `documentation source directory`_ and submit a `pull request`_. Account Validity ---------------- @@ -136,7 +134,7 @@ Federation :widths: 1 1 -.. _features.csv: +.. _documentation source directory: https://github.com/JOJ0/synadm/tree/master/doc/source/features.csv .. _feature request issue: https://github.com/JOJ0/synadm/issues/new From 719ee5e64ab9a7e54b9f83c595d2f095afdce872 Mon Sep 17 00:00:00 2001 From: J0J0 Todos Date: Wed, 11 Sep 2024 22:45:46 +0200 Subject: [PATCH 53/72] Try keepspace option in features.rst for media csv --- doc/source/features.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/doc/source/features.rst b/doc/source/features.rst index 6d902350..7cbf2746 100644 --- a/doc/source/features.rst +++ b/doc/source/features.rst @@ -52,6 +52,7 @@ Media :file: features_media.csv :header: "Synapse Admin API","synadm command(s)" :widths: 1 1 + :keepspace: Purge History ------------- From 53076e736bcef91cb2f8971bf9545903eb3daa66 Mon Sep 17 00:00:00 2001 From: J0J0 Todos Date: Thu, 12 Sep 2024 09:34:55 +0200 Subject: [PATCH 54/72] Finally find a way to escape whitespace in rst to prevent creation of
html when using leading spaces for indentation. --- doc/source/features.rst | 1 + doc/source/features_media.csv | 4 ++-- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/doc/source/features.rst b/doc/source/features.rst index 7cbf2746..2d509a1f 100644 --- a/doc/source/features.rst +++ b/doc/source/features.rst @@ -141,3 +141,4 @@ Federation https://github.com/JOJ0/synadm/issues/new .. _pull request: https://github.com/JOJ0/synadm/blob/dev/CONTRIBUTING.md#submitting-your-work +.. |nbindent| unicode:: U+00A0 U+00A0 .. non-breaking two-space indentation diff --git a/doc/source/features_media.csv b/doc/source/features_media.csv index 45a803d3..de257f2a 100644 --- a/doc/source/features_media.csv +++ b/doc/source/features_media.csv @@ -1,6 +1,6 @@ "`Querying media `_","---" -" `List all media in a room `_",:option:`synadm media list -r` -" `List all media uploaded by a user `_",:option:`synadm media list -u` :option:`synadm user media -f` +"|nbindent| `List all media in a room `_",:option:`synadm media list -r` +"|nbindent| `List all media uploaded by a user `_",:option:`synadm media list -u` :option:`synadm user media -f` "`Quarantine media `_","---" " `Quarantining media by ID `_",:option:`synadm media quarantine -i` " `Remove media from quarantine by ID `_",:option:`synadm media unquarantine -i` From 4099d2ca712c78f8ff453fc8c1a83fe38c162ebb Mon Sep 17 00:00:00 2001 From: J0J0 Todos Date: Sat, 21 Sep 2024 09:17:31 +0200 Subject: [PATCH 55/72] scrape_docs requirement in setup.py, not txt file --- scrape_docs_requirements.txt | 1 - setup.py | 3 +++ 2 files changed, 3 insertions(+), 1 deletion(-) delete mode 100644 scrape_docs_requirements.txt diff --git a/scrape_docs_requirements.txt b/scrape_docs_requirements.txt deleted file mode 100644 index c1f5f713..00000000 --- a/scrape_docs_requirements.txt +++ /dev/null @@ -1 +0,0 @@ -beautifulsoup4 diff --git a/setup.py b/setup.py index 12be3a40..723df282 100755 --- a/setup.py +++ b/setup.py @@ -56,6 +56,9 @@ "click-option-group>=0.5.2", "dnspython" ], + extras_require=[ + "beautifulsoup4" + ] entry_points=""" [console_scripts] synadm=synadm.cli:root From 15d92a782136028962b02568d79feed9a14d4b47 Mon Sep 17 00:00:00 2001 From: J0J0 Todos Date: Tue, 24 Sep 2024 07:42:07 +0200 Subject: [PATCH 56/72] Rename rst whitespace replacer and finish tables - Shorten slightly: |nbindent| -> |indent| - Finish placing it in features_*.csv files --- doc/source/features.rst | 2 +- doc/source/features_media.csv | 22 +++++++++++----------- doc/source/features_rooms.csv | 20 ++++++++++---------- doc/source/features_users.csv | 26 +++++++++++++------------- 4 files changed, 35 insertions(+), 35 deletions(-) diff --git a/doc/source/features.rst b/doc/source/features.rst index 2d509a1f..e6ee5153 100644 --- a/doc/source/features.rst +++ b/doc/source/features.rst @@ -141,4 +141,4 @@ Federation https://github.com/JOJ0/synadm/issues/new .. _pull request: https://github.com/JOJ0/synadm/blob/dev/CONTRIBUTING.md#submitting-your-work -.. |nbindent| unicode:: U+00A0 U+00A0 .. non-breaking two-space indentation +.. |indent| unicode:: U+00A0 U+00A0 .. non-breaking two-space indentation diff --git a/doc/source/features_media.csv b/doc/source/features_media.csv index de257f2a..05fb5b23 100644 --- a/doc/source/features_media.csv +++ b/doc/source/features_media.csv @@ -1,15 +1,15 @@ "`Querying media `_","---" -"|nbindent| `List all media in a room `_",:option:`synadm media list -r` -"|nbindent| `List all media uploaded by a user `_",:option:`synadm media list -u` :option:`synadm user media -f` +"|indent| `List all media in a room `_",:option:`synadm media list -r` +"|indent| `List all media uploaded by a user `_",:option:`synadm media list -u` :option:`synadm user media -f` "`Quarantine media `_","---" -" `Quarantining media by ID `_",:option:`synadm media quarantine -i` -" `Remove media from quarantine by ID `_",:option:`synadm media unquarantine -i` -" `Quarantining media in a room `_",:option:`synadm media quarantine -r` -" `Quarantining all media of a user `_",:option:`synadm media quarantine -u` -" `Protecting media from being quarantined `_",:option:`synadm media protect MEDIA_ID` -" `Unprotecting media from being quarantined `_", +"|indent| `Quarantining media by ID `_",:option:`synadm media quarantine -i` +"|indent| `Remove media from quarantine by ID `_",:option:`synadm media unquarantine -i` +"|indent| `Quarantining media in a room `_",:option:`synadm media quarantine -r` +"|indent| `Quarantining all media of a user `_",:option:`synadm media quarantine -u` +"|indent| `Protecting media from being quarantined `_",:option:`synadm media protect MEDIA_ID` +"|indent| `Unprotecting media from being quarantined `_", "`Delete local media `_","---" -" `Delete a specific local media `_",:option:`synadm media delete -i` -" `Delete local media by date or size `_",:option:`synadm media delete -d` :option:`synadm media delete --size` -" `Delete media uploaded by a user `_", +"|indent| `Delete a specific local media `_",:option:`synadm media delete -i` +"|indent| `Delete local media by date or size `_",:option:`synadm media delete -d` :option:`synadm media delete --size` +"|indent| `Delete media uploaded by a user `_", "`Purge Remote Media API `_",:option:`synadm media purge -d` diff --git a/doc/source/features_rooms.csv b/doc/source/features_rooms.csv index d3b99586..1099607e 100644 --- a/doc/source/features_rooms.csv +++ b/doc/source/features_rooms.csv @@ -5,17 +5,17 @@ "`Room Messages API `_", "`Room Timestamp to Event API `_", "`Block Room API `_","---" -" `Block or unblock a room `_",:option:`synadm room block -b` :option:`synadm room block -u` -" `Get block status `_",:option:`synadm room block-status ROOM_ID` +"|indent| `Block or unblock a room `_",:option:`synadm room block -b` :option:`synadm room block -u` +"|indent| `Get block status `_",:option:`synadm room block-status ROOM_ID` "`Delete Room API `_","---" -" `Version 1 (old version) `_",:option:`synadm room delete --v1` -" `Version 2 (new version) `_",:option:`synadm room delete ROOM_ID` -" `Status of deleting rooms `_","---" -" `Query by room_id `_",:option:`synadm room delete-status -r` -" `Query by delete_id `_",:option:`synadm room delete-status -d` -" `Undoing room deletions `_", +"|indent| `Version 1 (old version) `_",:option:`synadm room delete --v1` +"|indent| `Version 2 (new version) `_",:option:`synadm room delete ROOM_ID` +"|indent| `Status of deleting rooms `_","---" +"|indent| |indent| `Query by room_id `_",:option:`synadm room delete-status -r` +"|indent| |indent| `Query by delete_id `_",:option:`synadm room delete-status -d` +"|indent| `Undoing room deletions `_", "`Make Room Admin API `_",:option:`synadm room make-admin -u` "`Forward Extremities Admin API `_", -" `Check for forward extremities `_", -" `Deleting forward extremities `_", +"|indent| `Check for forward extremities `_", +"|indent| `Deleting forward extremities `_", "`Event Context API `_", diff --git a/doc/source/features_users.csv b/doc/source/features_users.csv index bafda52b..7d3c4be7 100644 --- a/doc/source/features_users.csv +++ b/doc/source/features_users.csv @@ -1,8 +1,8 @@ "`Query User Account `_",:option:`synadm user details USER_ID` "`Create or modify account `_",:option:`synadm user modify USER_ID` "`List Accounts `_","---" -" `List Accounts (V2) `_",:option:`synadm user list -f` -" `List Accounts (V3) `_", +"|indent| `List Accounts (V2) `_",:option:`synadm user list -f` +"|indent| `List Accounts (V3) `_", "`Query current sessions for a user `_",:option:`synadm user whois USER_ID` "`Deactivate Account `_",:option:`synadm user deactivate USER_ID` "`Reset password `_",:option:`synadm user password USER_ID` @@ -11,23 +11,23 @@ "`List room memberships of a user `_",:option:`synadm user membership USER_ID` "`Account Data `_", "`User media `_","---" -" `List media uploaded by a user `_", -" `Delete media uploaded by a user `_",:option:`synadm user media -f` :option:`synadm media list -u` +"|indent| `List media uploaded by a user `_", +"|indent| `Delete media uploaded by a user `_",:option:`synadm user media -f` :option:`synadm media list -u` "`Login as a user `_",:option:`synadm user login USER_ID` "`Allow replacing master cross-signing key without... `_", "`User devices `_","---" -" `List all devices `_",:option:`synadm user prune-devices --list-only` -" `Create a device `_", -" `Delete multiple devices `_",:option:`synadm user prune-devices -d` :option:`synadm user prune-devices -s` -" `Show a device `_",:option:`synadm user prune-devices --list-only` (-i) -" `Update a device `_", -" `Delete a device `_",:option:`synadm user prune-devices -i` +"|indent| `List all devices `_",:option:`synadm user prune-devices --list-only` +"|indent| `Create a device `_", +"|indent| `Delete multiple devices `_",:option:`synadm user prune-devices -d` :option:`synadm user prune-devices -s` +"|indent| `Show a device `_",:option:`synadm user prune-devices --list-only` (-i) +"|indent| `Update a device `_", +"|indent| `Delete a device `_",:option:`synadm user prune-devices -i` "`List all pushers `_", "`Controlling whether a user is shadow-banned `_",:option:`synadm user shadow-ban USER_ID` :option:`synadm user shadow-ban --unban` "`Override ratelimiting for users `_","---" -" `Get status of ratelimit `_", -" `Set ratelimit `_", -" `Delete ratelimit `_", +"|indent| `Get status of ratelimit `_", +"|indent| `Set ratelimit `_", +"|indent| `Delete ratelimit `_", "`Check username availability `_", "`Find a user based on their ID in an auth provider `_",:option:`synadm user 3pid ADDRESS` "`Find a user based on their Third Party ID `_",:option:`synadm user auth-provider EXTERNAL_USER_ID` From 97d2934dd538b9d17106b480df174df8f8529f7c Mon Sep 17 00:00:00 2001 From: J0J0 Todos Date: Tue, 24 Sep 2024 08:06:19 +0200 Subject: [PATCH 57/72] Add misc section features.rst and csv table containing synadm commands not directly (or not at all) related to a Synapse Admin API. --- doc/source/features.rst | 8 ++++++++ doc/source/features_miscellaneous.csv | 5 +++++ 2 files changed, 13 insertions(+) create mode 100644 doc/source/features_miscellaneous.csv diff --git a/doc/source/features.rst b/doc/source/features.rst index e6ee5153..61029558 100644 --- a/doc/source/features.rst +++ b/doc/source/features.rst @@ -134,6 +134,14 @@ Federation :header: "Synapse Admin API","synadm command(s)" :widths: 1 1 +Miscellaneous +------------- + +.. csv-table:: + :file: features_miscellaneous.csv + :header: "Description","synadm command(s)" + :widths: 1 1 + .. _documentation source directory: https://github.com/JOJ0/synadm/tree/master/doc/source/features.csv diff --git a/doc/source/features_miscellaneous.csv b/doc/source/features_miscellaneous.csv new file mode 100644 index 00000000..1304c28b --- /dev/null +++ b/doc/source/features_miscellaneous.csv @@ -0,0 +1,5 @@ +"The Configurator",:option:`synadm config -u` +"Any Synapse Admin API",:option:`synadm raw ENDPOINT` +"Native Matrix API Helpers","---" +"|indent| Matrix User Login",:option:`synadm matrix login USER_ID` +"|indent| Any Matrix API",:option:`synadm matrix raw ENDPOINT` \ No newline at end of file From 67549999b61833bf3e91d4360350cfcf11e0834a Mon Sep 17 00:00:00 2001 From: J0J0 Todos Date: Tue, 24 Sep 2024 08:20:01 +0200 Subject: [PATCH 58/72] Fix user media command position in features_users.csv --- doc/source/features_users.csv | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/source/features_users.csv b/doc/source/features_users.csv index 7d3c4be7..e73d3eb3 100644 --- a/doc/source/features_users.csv +++ b/doc/source/features_users.csv @@ -11,8 +11,8 @@ "`List room memberships of a user `_",:option:`synadm user membership USER_ID` "`Account Data `_", "`User media `_","---" -"|indent| `List media uploaded by a user `_", -"|indent| `Delete media uploaded by a user `_",:option:`synadm user media -f` :option:`synadm media list -u` +"|indent| `List media uploaded by a user `_",:option:`synadm user media -f` :option:`synadm media list -u` +"|indent| `Delete media uploaded by a user `_", "`Login as a user `_",:option:`synadm user login USER_ID` "`Allow replacing master cross-signing key without... `_", "`User devices `_","---" From b5570bc83bc05b675f2b44a494a4ab46ddc9a70c Mon Sep 17 00:00:00 2001 From: Jackson Date: Tue, 24 Sep 2024 10:18:42 +0200 Subject: [PATCH 59/72] fix extras_require 1. must be a dict 2. missing comma --- setup.py | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/setup.py b/setup.py index 723df282..8c467752 100755 --- a/setup.py +++ b/setup.py @@ -56,9 +56,11 @@ "click-option-group>=0.5.2", "dnspython" ], - extras_require=[ - "beautifulsoup4" - ] + extras_require={ + "scrape_docs": [ + "beautifulsoup4" + ], + }, entry_points=""" [console_scripts] synadm=synadm.cli:root From 3bb915f8179d63c8fdbb55e0a8d4f7e4aa536914 Mon Sep 17 00:00:00 2001 From: Jackson Date: Tue, 24 Sep 2024 10:19:00 +0200 Subject: [PATCH 60/72] correct prerequisites command in scrape_docs.py --- scrape_docs.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/scrape_docs.py b/scrape_docs.py index 26f4d698..ebfe4599 100755 --- a/scrape_docs.py +++ b/scrape_docs.py @@ -1,5 +1,5 @@ #!/usr/bin/env python -# Prerequisites: pip install -r scrape_docs_requirements.txt +# Prerequisites: pip install -e .[scrape_docs] import click from bs4 import BeautifulSoup From 02ef1696a2f8d722b60e172a0c9e8bbb64deac9c Mon Sep 17 00:00:00 2001 From: J0J0 Todos Date: Sat, 28 Sep 2024 07:48:55 +0200 Subject: [PATCH 61/72] scrape_docs escape square brackets in install command --- scrape_docs.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/scrape_docs.py b/scrape_docs.py index ebfe4599..198ed7bf 100755 --- a/scrape_docs.py +++ b/scrape_docs.py @@ -1,5 +1,5 @@ #!/usr/bin/env python -# Prerequisites: pip install -e .[scrape_docs] +# Prerequisites: pip install -e '.[scrape_docs]' import click from bs4 import BeautifulSoup From b1712b7d9c83d99846ca9f964c4b127b1e0b68ca Mon Sep 17 00:00:00 2001 From: J0J0 Todos Date: Sat, 28 Sep 2024 07:56:47 +0200 Subject: [PATCH 62/72] scrape_docs add usage info to header comment but leave out the fact that it's not an installed script and has to be called including path ./ or whatever... --- scrape_docs.py | 1 + 1 file changed, 1 insertion(+) diff --git a/scrape_docs.py b/scrape_docs.py index 198ed7bf..08db6bf9 100755 --- a/scrape_docs.py +++ b/scrape_docs.py @@ -1,5 +1,6 @@ #!/usr/bin/env python # Prerequisites: pip install -e '.[scrape_docs]' +# Usage: scrape_docs.py --help import click from bs4 import BeautifulSoup From 1b5e2c6652da6d85d35c907a7f09c2f0db8475f5 Mon Sep 17 00:00:00 2001 From: J0J0 Todos Date: Sat, 28 Sep 2024 08:34:45 +0200 Subject: [PATCH 63/72] CONTRIBUTING.md feature coverage documentation - Link to "Synapse Admin API Coverage" page instead of README.md chapter - Shorten bullet points text in both "Types of Contribution" sections. - Add "Feature Coverage Documentation" chapter describing the purpose of the page, how to maintain using scrape_docs.py --- CONTRIBUTING.md | 21 +++++++++++++++++---- 1 file changed, 17 insertions(+), 4 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e5c18b8b..df2388d5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -6,6 +6,7 @@ - [Programming](#programming) - [Submitting Your Work](#submitting-your-work) - [Expectations Regarding Timelines](#expectations-regarding-timelines) +- [Feature Coverage Documentation](#feature-coverage-documentation) - [Discuss \& Design First](#discuss--design-first) - [Getting the Source \& Installing](#getting-the-source--installing) - [Command Design](#command-design) @@ -27,16 +28,15 @@ No matter if you're a programmer or not there are many ways to contribute to the ### Non-Programming * [Set up synadm](README.md#installation) and report whether the installation, configuration and update processes work as described or could be improved. We don't have the resources to test on many operating systems, but you can [let us know](https://matrix.to/#/%23synadm%3Apeek-a-boo.at?via=jacksonchen666.com&via=maclemon.at&via=matrix.org&via=raim.ist) if it does work. -* Help keeping the [Implementation Status / Commands List](README.md#implementation-status--commands-list) chapter up to date. The Synapse project is steadily releasing new features for the _Synapse Admin API_. We can't keep up with updating this list but still think it is a handy overview of what's supported and what isn't. -* Help prioritizing what to code next: Pick a feature from the list you find in the [Implementation Status / Commands List](README.md#implementation-status--commands-list) chapter, open a GitHub issue and tell us what it is. If you don't find the feature in the list, please add it! +* Help keep the features list on [Synapse Admin API Coverage](https://synadm.readthedocs.io/en/latest/features.html) up to date. * Improve the docs: The end-user documentation is entirely realized with the typical online help of Unix commands, an option named`--help/-h`. We believe that a top-priority in designing CLI tools is getting this information right. Spelling, wording and of course technical correctness are equally important. If it's not easily possible to stay brief and technically precise at the same time, we believe it is OK to prioritize precision over shortness. We also have documentation made with _Sphinx_ [available online](https://synadm.readthedocs.io/en/latest/index_cli_reference.html). ### Programming -* Pick an open issue on GitHub or an unticked feature from the [Implementation Status / Commands List](README.md#implementation-status--commands-list) chapter, start implementing and submit a pull-request when you are ready to receive our feedback. +* Pick an open issue on GitHub or a [not yet supported Synapse Admin API](https://synadm.readthedocs.io/en/latest/features.html), start implementing and submit a pull-request when you are ready to receive our feedback. * If you'd like to receive "early feedback" even though you think your code is not ready yet, submit your PR already and set it to draft state. You can then mention us (`@` then followed by a GitHub username). * It's ok to open a Draft PR even if you don't want our feedback yet but it helps you in any way. We won't bother you until you ping us. -* Read the [Synapse Admin API docs](https://github.com/matrix-org/synapse/tree/master/docs/admin_api), pick a feature, implement it and send a pull-request. Don't forget to check if the feature is listed in the [Implementation Status / Commands List](README.md#implementation-status--commands-list) chapter already. If not, please add the command to the list (preferably in a separate commit). +* Don't forget to check if the feature you are submitting is listed on [Synapse Admin API Coverage](https://synadm.readthedocs.io/en/latest/features.html) already. If not, please add it to the corresponding table (preferably in a separate commit). ## Submitting Your Work @@ -60,6 +60,19 @@ We are maintaining `synadm` in our spare time and currently are not sponsored by - Unfortunately we often see contributors submitting PR's, correcting a few of our suggested changes but then disappear, so if you realize you won't find the time at all to continue your work, **please just let us know**. - We believe that even the tiniest feature deserves a timely release. Sometimes we just can't make it soon enough because we don't find the time or we wait for something else because it makes sense to be released together. If a feature you submitted is merged and you'd need it urgently to be available on PyPi, **please let us know**. +## Feature Coverage Documentation + +We keep track of which Synapse Admin API's `synadm` supports in a set of tables on [Synapse Admin API Coverage](https://synadm.readthedocs.io/en/latest/features.html). The structure of this page follows the layout of the official [Synapse Admin API documentation](https://element-hq.github.io/synapse/latest/usage/administration/admin_api/index.html). Each table represents one main chapter of the Synapse documentation. + +In our documentation source, the page is defined by [features.rst](https://github.com/JOJ0/synadm/blob/master/doc/source/features.rst), which contains multiple CSV files, each representing a table. To assist with maintaining this page, we offer a [web scraper tool](https://github.com/JOJ0/synadm/blob/master/scrape_docs.py) that pulls data from the Synapse Admin API docs and creates an initial version of such a CSV table. A basic usage example is + +``` +./scrape_docs.py -o csv https://element-hq.github.io/synapse/latest/admin_api/rooms.html +``` + +which prints a two-column CSV table containing restructuredText formatted hyperlinks in the left column. A corresponding `synadm` command is supposed to be added to the right column manually. + +For more information see `scrape_docs.py --help` and the [existing CSV files](https://github.com/JOJ0/synadm/tree/master/doc/source/features). ## Discuss & Design First From 14ca3678857572c36484a598c2da4173606466d3 Mon Sep 17 00:00:00 2001 From: Jackson Date: Tue, 24 Sep 2024 10:33:18 +0200 Subject: [PATCH 64/72] delete features.csv seems unused --- doc/source/features.csv | 182 ---------------------------------------- 1 file changed, 182 deletions(-) delete mode 100644 doc/source/features.csv diff --git a/doc/source/features.csv b/doc/source/features.csv deleted file mode 100644 index d953ec4a..00000000 --- a/doc/source/features.csv +++ /dev/null @@ -1,182 +0,0 @@ -Account validity API -==================== -"Synapse Admin API","synadm command(s)" -"`Renew account `_", - - -Delete Group API -================ -"Synapse Admin API","synadm command(s)" -"`Delete a local group `_",:option:`synadm group delete -h` - - -Background Updates API -====================== -"Synapse Admin API","synadm command(s)" -"`Status `_", -"`Enabled `_", -"`Run `_", - - -Event Reports API -================= -"Synapse Admin API","synadm command(s)" -"`Show reported events `_", -"`Show details of a specific event report `_", -"`Delete a specific event report `_", - - -Experimental Features API -========================= -"`Enabling/Disabling Features `_", -"`Listing Enabled Features `_", - - -Media API -========= -"Synapse Admin API","synadm command(s)" -"`Querying media `_","---" -" `List all media in a room `_",:option:`synadm media list -r` -" `List all media uploaded by a user `_",:option:`synadm media list -u` :option:`synadm user media -f` -"`Quarantine media `_","---" -" `Quarantining media by ID `_",:option:`synadm media quarantine -i` -" `Remove media from quarantine by ID `_",:option:`synadm media unquarantine -i` -" `Quarantining media in a room `_",:option:`synadm media quarantine -r` -" `Quarantining all media of a user `_",:option:`synadm media quarantine -u` -" `Protecting media from being quarantined `_",:option:`synadm media protect MEDIA_ID` -" `Unprotecting media from being quarantined `_", -"`Delete local media `_","---" -" `Delete a specific local media `_",:option:`synadm media delete -i` -" `Delete local media by date or size `_",:option:`synadm media delete -d` :option:`synadm media delete --size` -" `Delete media uploaded by a user `_", -"`Purge Remote Media API `_",:option:`synadm media purge -d` - - -Purge History API -================= -"Synapse Admin API","synadm command(s)" -"`Purge history `_",:option:`synadm history purge -i` -"`Purge status query `_",:option:`synadm history purge-status PURGE_ID` - - -Register Users API -================== -"`Shared-Secret Registration `_", - - -Registration Tokens API -======================= -"Synapse Admin API","synadm command(s)" -"`Registration token objects `_","---" -"`List all tokens `_",:option:`synadm regtok list -v` -"`Get one token `_",:option:`synadm regtok details TOKEN` -"`Create token `_",:option:`synadm regtok new -n` -"`Update token `_",:option:`synadm regtok update TOKEN` -"`Delete token `_",:option:`synadm regtok delete TOKEN` - - -Manipulate Room Mamebership API -=============================== -"Synapse Admin API","synadm command(s)" -"`Edit Room Membership API `_",:option:`synadm room join ROOM_ID_OR_ALIAS` - - -Rooms API -========= -"Synapse Admin API","synadm command(s)" -"`List Room API `_",:option:`synadm room list -f` -"`Room Details API `_",:option:`synadm room details ROOM_ID` -"`Room Members API `_",:option:`synadm room members ROOM_ID` -"`Room State API `_",:option:`synadm room state ROOM_ID` -"`Room Messages API `_", -"`Room Timestamp to Event API `_", -"`Block Room API `_","---" -" `Block or unblock a room `_",:option:`synadm room block -b` :option:`synadm room block -u` -" `Get block status `_",:option:`synadm room block-status ROOM_ID` -"`Delete Room API `_","---" -" `Version 1 (old version) `_",:option:`synadm room delete --v1` -" `Version 2 (new version) `_",:option:`synadm room delete ROOM_ID` -" `Status of deleting rooms `_","---" -" `Query by room_id `_",:option:`synadm room delete-status -r` -" `Query by delete_id `_",:option:`synadm room delete-status -d` -" `Undoing room deletions `_", -"`Make Room Admin API `_",:option:`synadm room make-admin -u` -"`Forward Extremities Admin API `_", -" `Check for forward extremities `_", -" `Deleting forward extremities `_", -"`Event Context API `_", - - -Server Notices API -================== -"Synapse Admin API","synadm command(s)" -"`Server Notices `_",:option:`synadm notice send TO` - -Statistics -========== -"`Users' media usage statistics `_", -"`Get largest rooms by size in database `_", - - -User Admin API -============== -"Synapse Admin API","synadm command(s)" -"`Query User Account `_",:option:`synadm user details USER_ID` -"`Create or modify account `_",:option:`synadm user modify USER_ID` -"`List Accounts `_","---" -" `List Accounts (V2) `_",:option:`synadm user list -f` -" `List Accounts (V3) `_", -"`Query current sessions for a user `_",:option:`synadm user whois USER_ID` -"`Deactivate Account `_",:option:`synadm user deactivate USER_ID` -"`Reset password `_",:option:`synadm user password USER_ID` -"`Get whether a user is a server administrator or not `_", -"`Change whether a user is a server administrator or not `_", -"`List room memberships of a user `_",:option:`synadm user membership USER_ID` -"`Account Data `_", -"`User media `_","---" -" `List media uploaded by a user `_", -" `Delete media uploaded by a user `_",:option:`synadm user media -f` :option:`synadm media list -u` -"`Login as a user `_",:option:`synadm user login USER_ID` -"`Allow replacing master cross-signing key without... `_", -"`User devices `_","---" -" `List all devices `_",:option:`synadm user prune-devices --list-only` -" `Create a device `_", -" `Delete multiple devices `_",:option:`synadm user prune-devices -d` :option:`synadm user prune-devices -s` -" `Show a device `_",:option:`synadm user prune-devices --list-only` (-i) -" `Update a device `_", -" `Delete a device `_",:option:`synadm user prune-devices -i` -"`List all pushers `_", -"`Controlling whether a user is shadow-banned `_",:option:`synadm user shadow-ban USER_ID` :option:`synadm user shadow-ban --unban` -"`Override ratelimiting for users `_","---" -" `Get status of ratelimit `_", -" `Set ratelimit `_", -" `Delete ratelimit `_", -"`Check username availability `_", -"`Find a user based on their ID in an auth provider `_",:option:`synadm user 3pid ADDRESS` -"`Find a user based on their Third Party ID `_",:option:`synadm user auth-provider EXTERNAL_USER_ID` - - -Version API -=========== -"Synapse Admin API","synadm command(s)" -"`Version API `_",:option:`synadm --version` - - -Federation API -============== -"Synapse Admin API","synadm command(s)" -"`List of destinations `_", -"`Destination Details API `_", -"`Destination rooms `_", -"`Reset connection timeout `_", - - -Miscellaneous -============= -"Synapse Admin API","synadm command(s)" -"---",:doc:`synadm.cli.config` -"Any Synapse Admin API",:doc:`synadm.cli.raw` -"Native Matrix API Helpers",:doc:`synadm.cli.matrix` -" Matrix User Login",:option:`synadm matrix login USER_ID` -" Any Matrix API",:option:`synadm matrix raw ENDPOINT` - From 59a339823402a9a9613ce217de0affb9c7e69492 Mon Sep 17 00:00:00 2001 From: Jackson Date: Tue, 24 Sep 2024 10:33:24 +0200 Subject: [PATCH 65/72] move *.csv to a dir and github link to it --- doc/source/features.rst | 36 +++++++++---------- .../account_validity.csv} | 0 .../background_updates.csv} | 0 .../delete_group.csv} | 0 .../event_reports.csv} | 0 .../experimental_features.csv} | 0 .../federation.csv} | 0 .../manipulate_room_membership.csv} | 0 .../media.csv} | 0 .../miscellaneous.csv} | 0 .../purge_history.csv} | 0 .../register_users.csv} | 0 .../registration_tokens.csv} | 0 .../rooms.csv} | 0 .../server_notices.csv} | 0 .../server_version.csv} | 0 .../statistics.csv} | 0 .../users.csv} | 0 18 files changed, 18 insertions(+), 18 deletions(-) rename doc/source/{features_account_validity.csv => features/account_validity.csv} (100%) rename doc/source/{features_background_updates.csv => features/background_updates.csv} (100%) rename doc/source/{features_delete_group.csv => features/delete_group.csv} (100%) rename doc/source/{features_event_reports.csv => features/event_reports.csv} (100%) rename doc/source/{features_experimental_features.csv => features/experimental_features.csv} (100%) rename doc/source/{features_federation.csv => features/federation.csv} (100%) rename doc/source/{features_manipulate_room_membership.csv => features/manipulate_room_membership.csv} (100%) rename doc/source/{features_media.csv => features/media.csv} (100%) rename doc/source/{features_miscellaneous.csv => features/miscellaneous.csv} (100%) rename doc/source/{features_purge_history.csv => features/purge_history.csv} (100%) rename doc/source/{features_register_users.csv => features/register_users.csv} (100%) rename doc/source/{features_registration_tokens.csv => features/registration_tokens.csv} (100%) rename doc/source/{features_rooms.csv => features/rooms.csv} (100%) rename doc/source/{features_server_notices.csv => features/server_notices.csv} (100%) rename doc/source/{features_server_version.csv => features/server_version.csv} (100%) rename doc/source/{features_statistics.csv => features/statistics.csv} (100%) rename doc/source/{features_users.csv => features/users.csv} (100%) diff --git a/doc/source/features.rst b/doc/source/features.rst index 61029558..507451df 100644 --- a/doc/source/features.rst +++ b/doc/source/features.rst @@ -9,7 +9,7 @@ Account Validity ---------------- .. csv-table:: - :file: features_account_validity.csv + :file: features/account_validity.csv :header: "Synapse Admin API","synadm command(s)" :widths: 1 1 @@ -17,7 +17,7 @@ Background Updates ------------------ .. csv-table:: - :file: features_background_updates.csv + :file: features/background_updates.csv :header: "Synapse Admin API","synadm command(s)" :widths: 1 1 @@ -25,7 +25,7 @@ Delete Group ------------ .. csv-table:: - :file: features_delete_group.csv + :file: features/delete_group.csv :header: "Synapse Admin API","synadm command(s)" :widths: 1 1 @@ -33,7 +33,7 @@ Event Reports ------------- .. csv-table:: - :file: features_event_reports.csv + :file: features/event_reports.csv :header: "Synapse Admin API","synadm command(s)" :widths: 1 1 @@ -41,7 +41,7 @@ Experimental Features --------------------- .. csv-table:: - :file: features_experimental_features.csv + :file: features/experimental_features.csv :header: "Synapse Admin API","synadm command(s)" :widths: 1 1 @@ -49,7 +49,7 @@ Media ----- .. csv-table:: - :file: features_media.csv + :file: features/media.csv :header: "Synapse Admin API","synadm command(s)" :widths: 1 1 :keepspace: @@ -58,7 +58,7 @@ Purge History ------------- .. csv-table:: - :file: features_purge_history.csv + :file: features/purge_history.csv :header: "Synapse Admin API","synadm command(s)" :widths: 1 1 @@ -66,7 +66,7 @@ Register Users -------------- .. csv-table:: - :file: features_register_users.csv + :file: features/register_users.csv :header: "Synapse Admin API","synadm command(s)" :widths: 1 1 @@ -74,7 +74,7 @@ Registration Tokens ------------------- .. csv-table:: - :file: features_registration_tokens.csv + :file: features/registration_tokens.csv :header: "Synapse Admin API","synadm command(s)" :widths: 1 1 @@ -82,7 +82,7 @@ Manipulate Room Membership -------------------------- .. csv-table:: - :file: features_manipulate_room_membership.csv + :file: features/manipulate_room_membership.csv :header: "Synapse Admin API","synadm command(s)" :widths: 1 1 @@ -90,7 +90,7 @@ Rooms ----- .. csv-table:: - :file: features_rooms.csv + :file: features/rooms.csv :header: "Synapse Admin API","synadm command(s)" :widths: 1 1 @@ -98,7 +98,7 @@ Server Notices -------------- .. csv-table:: - :file: features_server_notices.csv + :file: features/server_notices.csv :header: "Synapse Admin API","synadm command(s)" :widths: 1 1 @@ -106,7 +106,7 @@ Statistics ---------- .. csv-table:: - :file: features_statistics.csv + :file: features/statistics.csv :header: "Synapse Admin API","synadm command(s)" :widths: 1 1 @@ -114,7 +114,7 @@ Users ----- .. csv-table:: - :file: features_users.csv + :file: features/users.csv :header: "Synapse Admin API","synadm command(s)" :widths: 1 1 @@ -122,7 +122,7 @@ Server Version -------------- .. csv-table:: - :file: features_server_version.csv + :file: features/server_version.csv :header: "Synapse Admin API","synadm command(s)" :widths: 1 1 @@ -130,7 +130,7 @@ Federation ---------- .. csv-table:: - :file: features_federation.csv + :file: features/federation.csv :header: "Synapse Admin API","synadm command(s)" :widths: 1 1 @@ -138,13 +138,13 @@ Miscellaneous ------------- .. csv-table:: - :file: features_miscellaneous.csv + :file: features/miscellaneous.csv :header: "Description","synadm command(s)" :widths: 1 1 .. _documentation source directory: - https://github.com/JOJ0/synadm/tree/master/doc/source/features.csv + https://github.com/JOJ0/synadm/tree/master/doc/source/features/ .. _feature request issue: https://github.com/JOJ0/synadm/issues/new .. _pull request: diff --git a/doc/source/features_account_validity.csv b/doc/source/features/account_validity.csv similarity index 100% rename from doc/source/features_account_validity.csv rename to doc/source/features/account_validity.csv diff --git a/doc/source/features_background_updates.csv b/doc/source/features/background_updates.csv similarity index 100% rename from doc/source/features_background_updates.csv rename to doc/source/features/background_updates.csv diff --git a/doc/source/features_delete_group.csv b/doc/source/features/delete_group.csv similarity index 100% rename from doc/source/features_delete_group.csv rename to doc/source/features/delete_group.csv diff --git a/doc/source/features_event_reports.csv b/doc/source/features/event_reports.csv similarity index 100% rename from doc/source/features_event_reports.csv rename to doc/source/features/event_reports.csv diff --git a/doc/source/features_experimental_features.csv b/doc/source/features/experimental_features.csv similarity index 100% rename from doc/source/features_experimental_features.csv rename to doc/source/features/experimental_features.csv diff --git a/doc/source/features_federation.csv b/doc/source/features/federation.csv similarity index 100% rename from doc/source/features_federation.csv rename to doc/source/features/federation.csv diff --git a/doc/source/features_manipulate_room_membership.csv b/doc/source/features/manipulate_room_membership.csv similarity index 100% rename from doc/source/features_manipulate_room_membership.csv rename to doc/source/features/manipulate_room_membership.csv diff --git a/doc/source/features_media.csv b/doc/source/features/media.csv similarity index 100% rename from doc/source/features_media.csv rename to doc/source/features/media.csv diff --git a/doc/source/features_miscellaneous.csv b/doc/source/features/miscellaneous.csv similarity index 100% rename from doc/source/features_miscellaneous.csv rename to doc/source/features/miscellaneous.csv diff --git a/doc/source/features_purge_history.csv b/doc/source/features/purge_history.csv similarity index 100% rename from doc/source/features_purge_history.csv rename to doc/source/features/purge_history.csv diff --git a/doc/source/features_register_users.csv b/doc/source/features/register_users.csv similarity index 100% rename from doc/source/features_register_users.csv rename to doc/source/features/register_users.csv diff --git a/doc/source/features_registration_tokens.csv b/doc/source/features/registration_tokens.csv similarity index 100% rename from doc/source/features_registration_tokens.csv rename to doc/source/features/registration_tokens.csv diff --git a/doc/source/features_rooms.csv b/doc/source/features/rooms.csv similarity index 100% rename from doc/source/features_rooms.csv rename to doc/source/features/rooms.csv diff --git a/doc/source/features_server_notices.csv b/doc/source/features/server_notices.csv similarity index 100% rename from doc/source/features_server_notices.csv rename to doc/source/features/server_notices.csv diff --git a/doc/source/features_server_version.csv b/doc/source/features/server_version.csv similarity index 100% rename from doc/source/features_server_version.csv rename to doc/source/features/server_version.csv diff --git a/doc/source/features_statistics.csv b/doc/source/features/statistics.csv similarity index 100% rename from doc/source/features_statistics.csv rename to doc/source/features/statistics.csv diff --git a/doc/source/features_users.csv b/doc/source/features/users.csv similarity index 100% rename from doc/source/features_users.csv rename to doc/source/features/users.csv From d1a3eac3d3f4ab4555e5dd2666990c21bcce547e Mon Sep 17 00:00:00 2001 From: J0J0 Todos <2733783+JOJ0@users.noreply.github.com> Date: Mon, 30 Sep 2024 19:56:45 +0200 Subject: [PATCH 66/72] Apply review suggestions with corrected title We decided on "API to CLI Mapping" as the title of the links in the docs and the title of the chapter. Co-authored-by: Jackson --- CONTRIBUTING.md | 8 ++++---- doc/source/features.rst | 2 +- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index df2388d5..2be02243 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -28,15 +28,15 @@ No matter if you're a programmer or not there are many ways to contribute to the ### Non-Programming * [Set up synadm](README.md#installation) and report whether the installation, configuration and update processes work as described or could be improved. We don't have the resources to test on many operating systems, but you can [let us know](https://matrix.to/#/%23synadm%3Apeek-a-boo.at?via=jacksonchen666.com&via=maclemon.at&via=matrix.org&via=raim.ist) if it does work. -* Help keep the features list on [Synapse Admin API Coverage](https://synadm.readthedocs.io/en/latest/features.html) up to date. +* Help keep the features list on [API to CLI Mapping](https://synadm.readthedocs.io/en/latest/features.html) up to date. * Improve the docs: The end-user documentation is entirely realized with the typical online help of Unix commands, an option named`--help/-h`. We believe that a top-priority in designing CLI tools is getting this information right. Spelling, wording and of course technical correctness are equally important. If it's not easily possible to stay brief and technically precise at the same time, we believe it is OK to prioritize precision over shortness. We also have documentation made with _Sphinx_ [available online](https://synadm.readthedocs.io/en/latest/index_cli_reference.html). ### Programming -* Pick an open issue on GitHub or a [not yet supported Synapse Admin API](https://synadm.readthedocs.io/en/latest/features.html), start implementing and submit a pull-request when you are ready to receive our feedback. +* Pick an [open issue on GitHub](https://github.com/JOJ0/synadm/issues) or a not yet implemented [Synapse Admin API](https://synadm.readthedocs.io/en/latest/features.html) (see [API to CLI Mapping](https://synadm.readthedocs.io/en/latest/features.html)) and start implementing it, then submit a pull-request when you are ready. * If you'd like to receive "early feedback" even though you think your code is not ready yet, submit your PR already and set it to draft state. You can then mention us (`@` then followed by a GitHub username). * It's ok to open a Draft PR even if you don't want our feedback yet but it helps you in any way. We won't bother you until you ping us. -* Don't forget to check if the feature you are submitting is listed on [Synapse Admin API Coverage](https://synadm.readthedocs.io/en/latest/features.html) already. If not, please add it to the corresponding table (preferably in a separate commit). +* Don't forget to check if the feature you are submitting is listed on [API to CLI Mapping](https://synadm.readthedocs.io/en/latest/features.html) already. If not, please add it to the corresponding table (preferably in a separate commit). ## Submitting Your Work @@ -62,7 +62,7 @@ We are maintaining `synadm` in our spare time and currently are not sponsored by ## Feature Coverage Documentation -We keep track of which Synapse Admin API's `synadm` supports in a set of tables on [Synapse Admin API Coverage](https://synadm.readthedocs.io/en/latest/features.html). The structure of this page follows the layout of the official [Synapse Admin API documentation](https://element-hq.github.io/synapse/latest/usage/administration/admin_api/index.html). Each table represents one main chapter of the Synapse documentation. +We keep track of which Synapse Admin API's `synadm` supports in a set of tables on [API to CLI Mapping](https://synadm.readthedocs.io/en/latest/features.html). The structure of this page follows the layout of the official [Synapse Admin API documentation](https://element-hq.github.io/synapse/latest/usage/administration/admin_api/index.html). Each table represents one main chapter of the Synapse documentation. In our documentation source, the page is defined by [features.rst](https://github.com/JOJ0/synadm/blob/master/doc/source/features.rst), which contains multiple CSV files, each representing a table. To assist with maintaining this page, we offer a [web scraper tool](https://github.com/JOJ0/synadm/blob/master/scrape_docs.py) that pulls data from the Synapse Admin API docs and creates an initial version of such a CSV table. A basic usage example is diff --git a/doc/source/features.rst b/doc/source/features.rst index 507451df..088111f4 100644 --- a/doc/source/features.rst +++ b/doc/source/features.rst @@ -1,4 +1,4 @@ -Synapse Admin API Coverage +API to CLI Mapping ========================== The tables below show which Synapse Admin APIs are used by their corresponding ``synadm`` commands. From bbfc3bb471e945d2490cd383659892ff178f1086 Mon Sep 17 00:00:00 2001 From: J0J0 Todos Date: Tue, 1 Oct 2024 07:27:02 +0200 Subject: [PATCH 67/72] scrape_docs replace indentation spaces with rst replacer --- scrape_docs.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/scrape_docs.py b/scrape_docs.py index 08db6bf9..eac9e8d7 100755 --- a/scrape_docs.py +++ b/scrape_docs.py @@ -55,9 +55,10 @@ def scrape(output, url): if e.parent.name == h: # h1 is no spacing (decrease by 1), # h2 is 2 spaces, h3 is 4.... + # two literal spaces are replaced by '|indent| ' spacing_count = int(e.parent.name[-1]) - 1 for val in range(0, spacing_count * 2): - spacing += ' ' + spacing += '|indent| ' rst = f'{spacing}`{e.text} <{fulllink}>`_' if output == 'csv': left_col = f'"{rst}"' From 49c990d4d94f7593724e4f461b20799a7ee6d7ac Mon Sep 17 00:00:00 2001 From: J0J0 Todos Date: Wed, 2 Oct 2024 23:23:01 +0200 Subject: [PATCH 68/72] features.rst note on docs --- doc/source/features.rst | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/doc/source/features.rst b/doc/source/features.rst index 088111f4..83532660 100644 --- a/doc/source/features.rst +++ b/doc/source/features.rst @@ -3,7 +3,8 @@ API to CLI Mapping The tables below show which Synapse Admin APIs are used by their corresponding ``synadm`` commands. The left column's entries link to the official Synapse Admin API documentation, the right column's entries point to the ``synadm`` CLI reference. -To add missing entries to a table edit one of the CSV files in our `documentation source directory`_ and submit a `pull request`_. +To add missing entries to a table edit one of the CSV files in our `documentation source directory`_ and submit a `pull request`_. For more details on adding to the CSV tables, see `feature coverage documentation`_ + Account Validity ---------------- @@ -148,5 +149,7 @@ Miscellaneous .. _feature request issue: https://github.com/JOJ0/synadm/issues/new .. _pull request: - https://github.com/JOJ0/synadm/blob/dev/CONTRIBUTING.md#submitting-your-work + https://github.com/JOJ0/synadm/blob/master/CONTRIBUTING.md#submitting-your-work +.. _feature coverage documentation: + https://github.com/JOJ0/synadm/blob/master/CONTRIBUTING.md#feature-coverage-documentation .. |indent| unicode:: U+00A0 U+00A0 .. non-breaking two-space indentation From d57bab8d7ff855c2db5713dccb74f7ba9e94fd88 Mon Sep 17 00:00:00 2001 From: J0J0 Todos Date: Thu, 3 Oct 2024 10:03:13 +0200 Subject: [PATCH 69/72] features.rst shorten last intro text sentence --- doc/source/features.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/features.rst b/doc/source/features.rst index 83532660..2ce976a6 100644 --- a/doc/source/features.rst +++ b/doc/source/features.rst @@ -3,7 +3,7 @@ API to CLI Mapping The tables below show which Synapse Admin APIs are used by their corresponding ``synadm`` commands. The left column's entries link to the official Synapse Admin API documentation, the right column's entries point to the ``synadm`` CLI reference. -To add missing entries to a table edit one of the CSV files in our `documentation source directory`_ and submit a `pull request`_. For more details on adding to the CSV tables, see `feature coverage documentation`_ +To add missing entries to a table edit one of the CSV files in our `documentation source directory`_ and submit a `pull request`_ - see `feature coverage documentation`_ for details. Account Validity From c43d47c71b97e42c76ac35514265742fc6976e38 Mon Sep 17 00:00:00 2001 From: J0J0 Todos Date: Thu, 3 Oct 2024 10:57:13 +0200 Subject: [PATCH 70/72] contributing docs details on linking to cli reference --- CONTRIBUTING.md | 16 ++++++++++++++-- 1 file changed, 14 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2be02243..a2b0da1e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -70,9 +70,21 @@ In our documentation source, the page is defined by [features.rst](https://githu ./scrape_docs.py -o csv https://element-hq.github.io/synapse/latest/admin_api/rooms.html ``` -which prints a two-column CSV table containing restructuredText formatted hyperlinks in the left column. A corresponding `synadm` command is supposed to be added to the right column manually. +which prints a two-column CSV table containing restructuredText formatted hyperlinks in the left column. A corresponding `synadm` command is supposed to be added to the right hand side column manually. For example, you could add the following: + +``` +:option:`synadm user details USER_ID` +``` + +This would directly link to the `USER_ID` argument's documentation of that command. +Linking to an option is also possible: + +``` +:option:`synadm media list -r` +``` + +Due to a shortcoming of Sphinx it is currently not possible to link to a plain command (without any option or argument). Also see `scrape_docs.py --help` and the [existing CSV files](https://github.com/JOJ0/synadm/tree/master/doc/source/features). -For more information see `scrape_docs.py --help` and the [existing CSV files](https://github.com/JOJ0/synadm/tree/master/doc/source/features). ## Discuss & Design First From 9d96193d68fe6f04d3be564dc2edfd46123e51bc Mon Sep 17 00:00:00 2001 From: J0J0 Todos Date: Thu, 3 Oct 2024 13:48:29 +0200 Subject: [PATCH 71/72] scrape_docs csv out no headline output --- scrape_docs.py | 2 -- 1 file changed, 2 deletions(-) diff --git a/scrape_docs.py b/scrape_docs.py index eac9e8d7..51fdb6b5 100755 --- a/scrape_docs.py +++ b/scrape_docs.py @@ -35,8 +35,6 @@ def scrape(output, url): elements = soup.find_all([*any_heading_tag, 'a'],) if output == 'csv': - print('Change this headline as required') - print('================================\n') print('"Synapse Admin API","synadm command(s)"') for e in elements: From 7cfbadfd5116d8beeeeb91ae2f5469674daa592a Mon Sep 17 00:00:00 2001 From: J0J0 Todos Date: Thu, 3 Oct 2024 14:05:16 +0200 Subject: [PATCH 72/72] scrape_docs explain indentation space replacement --- scrape_docs.py | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/scrape_docs.py b/scrape_docs.py index 51fdb6b5..03200826 100755 --- a/scrape_docs.py +++ b/scrape_docs.py @@ -13,10 +13,11 @@ type=click.Choice(['debug', 'rst', 'csv']), show_choices=True, help='''Output format "debug" prints headline level, headline text and the scraped link/anchor; "rst" gives a restructuredText formatted hyperlink - including space-indentation according to headline levels; "csv" is a - two-column comma separated value format that includes the results of "rst" - as the left column's contents. Additionally "csv" adds a restructuredText - formatted headline above the table''') + including indentation according to headline levels. Spaces at the beginning + of lines have a special meaning in rst documents, thus the hardcoded + replacement marker "|indent|" is used; "csv" is a two-column comma + separated value format that includes the results of "rst" as the left + column's contents.''') @click.argument('URL') def scrape(output, url): '''Scrape one chapter of Admin API docs and spit out in various formats.