Skip to content

Commit

Permalink
Apply review suggestions with corrected title
Browse files Browse the repository at this point in the history
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 <jackson@jacksonchen666.com>
  • Loading branch information
JOJ0 and JacksonChen666 authored Sep 30, 2024
1 parent 59a3398 commit d1a3eac
Show file tree
Hide file tree
Showing 2 changed files with 5 additions and 5 deletions.
8 changes: 4 additions & 4 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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

Expand Down
2 changes: 1 addition & 1 deletion doc/source/features.rst
Original file line number Diff line number Diff line change
@@ -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.
Expand Down

0 comments on commit d1a3eac

Please sign in to comment.