Add an API vs command overview in table form to docs #149
Conversation
Word our links exactly as the chapters/toc links in Synapse docs are!
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.
in the left column. Use proper rst Syntax in the right column. Unfortunately we have to work around this bug: click-contrib/sphinx-click#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!
and for now leave latest Synapse version in link description. TBD how to handle deprecated/removed API's.
A first draft. Gets all anchors but only if a direct parent is a header tag.
and fix rst output format (trailing underscore)
fix existing data to use two spaces for indentation of subordinate api docs links and remove bulletpoints entirely in right column.
with the help of scraper.
and add indentation to Delete Room API subchapters
and actually even "editability".
and remove "Overview" suffix for main-api-docs-links
JOJ0
force-pushed
the
dev
branch
2 times, most recently
from
0a46a45
to
ac122ce
Compare
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!
- Shorten slightly: |nbindent| -> |indent| - Finish placing it in features_*.csv files
containing synadm commands not directly (or not at all) related to a Synapse Admin API.
1. must be a dict 2. missing comma
Yeah please do! Didn't come around to tidying up yet. Many thanks! |
but leave out the fact that it's not an installed script and has to be called including path ./ or whatever...
- 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
|
@JacksonChen666 please review my take on CONTRIBUTING.md: 1b5e2c6 Tried to shorten some existing sentences too, all nitpicks welcome!
In CONTRIBUTING.md maybe it would be good to state that linking to synadm commands is not perfect/flawed (options-links-only issues). What do you think? |
Hmm I see your point that "Synapse Admin API Coverage" might read a bit confusing (as if we would code the Synapse Admin API, which we don't) but now it feels like "synadm's API Coverage" is equally confusing but the other way round. My first impression was that we are talking about an API synadm is providing, which it isn't! You see my point? I think we need another round of brainstorming about the title! Some ideas for rethinking:
|
Actually that makes sense as well, I like "API vs. CLI mapping" |
Yeah I agree that that's the right direction. Decided that the "vs." does not feel perfect when we use "mapping". What do you think about these:
Which one better in your opinion @JacksonChen666? |
API to CLI Mapping |
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 <[email protected]>
|
Ok I'll finally merge it...
I documented this in CONTRIBUTING.md. What I left out on purpose is describing the spaces to Thanks for all the feedback, I hope I didn't mess up anything but I'd like to spare us another round of reviewing...it should be good enough. |
Later I'll try to create the things from scratch and let you know... somewhere. Probably here. |
...and on the way, do some minor fixes in our docs layout/TOC.
Preview here: https://synadm.readthedocs.io/en/dev/features.html
pip install beautifulsoup4; ./scrape_docs.py --helpfeatures.csvmanually but still saves some worksynadmcommands to CSV (right column) must also be done manuallysphinx-click, we can't link to a a command likesynadm user detaildirectly, we only can link to a command likesynadm user detail --optionorsynadm user detail USER_ID, therefore sometimes I linked to arbitrary--optionsjust to get as close as possible to the chapter in the CLI reference.