Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

API CLI mapping docs consistency #159

Merged
merged 3 commits into from
Oct 25, 2024
Merged

API CLI mapping docs consistency #159

merged 3 commits into from
Oct 25, 2024

Conversation

JacksonChen666
Copy link
Collaborator

Some changes to make CONTRIBUTING.md and scrape_docs.py more aligned with how it's currently formatted in the actual documentation

@JacksonChen666 JacksonChen666 added the documentation Improvements or additions to documentation label Oct 14, 2024
@JacksonChen666 JacksonChen666 requested a review from JOJ0 October 14, 2024 09:46
@JOJ0
Copy link
Owner

JOJ0 commented Oct 15, 2024

Thanks for improving the docs and also many thanks for trying to fix the "indentation level" handling in the scraper.

I checked this again and with rooms.html I get these differences:

scrape_docs in master:

"Synapse Admin API","synadm command(s)"
"`List Room API <https://element-hq.github.io/synapse/latest/admin_api/rooms.html#list-room-api>`_",
"`Room Details API <https://element-hq.github.io/synapse/latest/admin_api/rooms.html#room-details-api>`_",
"`Room Members API <https://element-hq.github.io/synapse/latest/admin_api/rooms.html#room-members-api>`_",
"`Room State API <https://element-hq.github.io/synapse/latest/admin_api/rooms.html#room-state-api>`_",
"`Room Messages API <https://element-hq.github.io/synapse/latest/admin_api/rooms.html#room-messages-api>`_",
"`Room Timestamp to Event API <https://element-hq.github.io/synapse/latest/admin_api/rooms.html#room-timestamp-to-event-api>`_",
"`Block Room API <https://element-hq.github.io/synapse/latest/admin_api/rooms.html#block-room-api>`_",
"|indent| |indent| `Block or unblock a room <https://element-hq.github.io/synapse/latest/admin_api/rooms.html#block-or-unblock-a-room>`_",
"|indent| |indent| `Get block status <https://element-hq.github.io/synapse/latest/admin_api/rooms.html#get-block-status>`_",
"`Delete Room API <https://element-hq.github.io/synapse/latest/admin_api/rooms.html#delete-room-api>`_",
"|indent| |indent| `Version 1 (old version) <https://element-hq.github.io/synapse/latest/admin_api/rooms.html#version-1-old-version>`_",
"|indent| |indent| `Version 2 (new version) <https://element-hq.github.io/synapse/latest/admin_api/rooms.html#version-2-new-version>`_",
"|indent| |indent| `Status of deleting rooms <https://element-hq.github.io/synapse/latest/admin_api/rooms.html#status-of-deleting-rooms>`_",
"|indent| |indent| |indent| |indent| `Query by room_id <https://element-hq.github.io/synapse/latest/admin_api/rooms.html#query-by-room_id>`_",
"|indent| |indent| |indent| |indent| `Query by delete_id <https://element-hq.github.io/synapse/latest/admin_api/rooms.html#query-by-delete_id>`_",
"|indent| |indent| |indent| |indent| `Response <https://element-hq.github.io/synapse/latest/admin_api/rooms.html#response>`_",
"|indent| |indent| `Undoing room deletions <https://element-hq.github.io/synapse/latest/admin_api/rooms.html#undoing-room-deletions>`_",
"`Make Room Admin API <https://element-hq.github.io/synapse/latest/admin_api/rooms.html#make-room-admin-api>`_",
"`Forward Extremities Admin API <https://element-hq.github.io/synapse/latest/admin_api/rooms.html#forward-extremities-admin-api>`_",
"|indent| |indent| `Check for forward extremities <https://element-hq.github.io/synapse/latest/admin_api/rooms.html#check-for-forward-extremities>`_",
"|indent| |indent| `Deleting forward extremities <https://element-hq.github.io/synapse/latest/admin_api/rooms.html#deleting-forward-extremities>`_",
"`Event Context API <https://element-hq.github.io/synapse/latest/admin_api/rooms.html#event-context-api>`_",


scrape_docs in this branch:

"`Block or unblock a room <https://element-hq.github.io/synapse/latest/admin_api/rooms.html#block-or-unblock-a-room>`_",
"`Get block status <https://element-hq.github.io/synapse/latest/admin_api/rooms.html#get-block-status>`_",
"`Version 1 (old version) <https://element-hq.github.io/synapse/latest/admin_api/rooms.html#version-1-old-version>`_",
"`Version 2 (new version) <https://element-hq.github.io/synapse/latest/admin_api/rooms.html#version-2-new-version>`_",
"`Status of deleting rooms <https://element-hq.github.io/synapse/latest/admin_api/rooms.html#status-of-deleting-rooms>`_",
"|indent| |indent| `Query by room_id <https://element-hq.github.io/synapse/latest/admin_api/rooms.html#query-by-room_id>`_",
"|indent| |indent| `Query by delete_id <https://element-hq.github.io/synapse/latest/admin_api/rooms.html#query-by-delete_id>`_",
"|indent| |indent| `Response <https://element-hq.github.io/synapse/latest/admin_api/rooms.html#response>`_",
"`Undoing room deletions <https://element-hq.github.io/synapse/latest/admin_api/rooms.html#undoing-room-deletions>`_",
"`Check for forward extremities <https://element-hq.github.io/synapse/latest/admin_api/rooms.html#check-for-forward-extremities>`_",
"`Deleting forward extremities <https://element-hq.github.io/synapse/latest/admin_api/rooms.html#deleting-forward-extremities>`_",


the actual documentation:

"`List Room API <https://element-hq.github.io/synapse/latest/admin_api/rooms.html#list-room-api>`_",:option:`synadm room list -f`
"`Room Details API <https://element-hq.github.io/synapse/latest/admin_api/rooms.html#room-details-api>`_",:option:`synadm room details ROOM_ID`
"`Room Members API <https://element-hq.github.io/synapse/latest/admin_api/rooms.html#room-members-api>`_",:option:`synadm room members ROOM_ID`
"`Room State API <https://element-hq.github.io/synapse/latest/admin_api/rooms.html#room-state-api>`_",:option:`synadm room state ROOM_ID`
"`Room Messages API <https://element-hq.github.io/synapse/latest/admin_api/rooms.html#room-messages-api>`_",
"`Room Timestamp to Event API <https://element-hq.github.io/synapse/latest/admin_api/rooms.html#room-timestamp-to-event-api>`_",
"`Block Room API <https://element-hq.github.io/synapse/latest/admin_api/rooms.html#block-room-api>`_","---"
"|indent| `Block or unblock a room <https://element-hq.github.io/synapse/latest/admin_api/rooms.html#block-or-unblock-a-room>`_",:option:`synadm room block -b` :option:`synadm room block -u`
"|indent| `Get block status <https://element-hq.github.io/synapse/latest/admin_api/rooms.html#get-block-status>`_",:option:`synadm room block-status ROOM_ID`
"`Delete Room API <https://element-hq.github.io/synapse/latest/admin_api/rooms.html#delete-room-api>`_","---"
"|indent| `Version 1 (old version) <https://element-hq.github.io/synapse/latest/admin_api/rooms.html#version-1-old-version>`_",:option:`synadm room delete --v1`
"|indent| `Version 2 (new version) <https://element-hq.github.io/synapse/latest/admin_api/rooms.html#version-2-new-version>`_",:option:`synadm room delete ROOM_ID`
"|indent| `Status of deleting rooms <https://element-hq.github.io/synapse/latest/admin_api/rooms.html#status-of-deleting-rooms>`_","---"
"|indent| |indent| `Query by room_id <https://element-hq.github.io/synapse/latest/admin_api/rooms.html#query-by-room_id>`_",:option:`synadm room delete-status -r`
"|indent| |indent| `Query by delete_id <https://element-hq.github.io/synapse/latest/admin_api/rooms.html#query-by-delete_id>`_",:option:`synadm room delete-status -d`
"|indent| `Undoing room deletions <https://element-hq.github.io/synapse/latest/admin_api/rooms.html#undoing-room-deletions>`_",
"`Make Room Admin API <https://element-hq.github.io/synapse/latest/admin_api/rooms.html#make-room-admin-api>`_",:option:`synadm room make-admin -u`
"`Forward Extremities Admin API <https://element-hq.github.io/synapse/latest/admin_api/rooms.html#forward-extremities-admin-api>`_",
"|indent| `Check for forward extremities <https://element-hq.github.io/synapse/latest/admin_api/rooms.html#check-for-forward-extremities>`_",
"|indent| `Deleting forward extremities <https://element-hq.github.io/synapse/latest/admin_api/rooms.html#deleting-forward-extremities>`_",
"`Event Context API <https://element-hq.github.io/synapse/latest/admin_api/rooms.html#event-context-api>`_",

So it seems that removing h1 from the headers list removes too much of the content that we still want to have in the docs.

@JOJ0
scrape_docs: Fix h1 exclusion and refactor
bc60b17 
- h1 tag shouldn't be excluded in output
- Refactor for readability: Add a separate function for finding "how
  many indentations" are required.
@JOJ0 JOJ0 force-pushed the api-cli-mapping-consistency branch from 69e2fb9 to bc60b17 Compare October 15, 2024 06:33
@JOJ0
Copy link
Owner

JOJ0 commented Oct 15, 2024 •
edited
Loading

Ok please see bc60b17, I tried to refactor to make it just a little more readable. Check out -o debug, it now displays on how many required indentations it decided. HTH, some nitpicking on my variable naming is in order. It's early ;-)

@JOJ0
Copy link
Owner

JOJ0 commented Oct 16, 2024 •
edited
Loading

Forgot to add what the final outcome of my changes are - almost identical to what we have in the actual docs now:

"`List Room API <https://element-hq.github.io/synapse/latest/admin_api/rooms.html#list-room-api>`_",
"`Room Details API <https://element-hq.github.io/synapse/latest/admin_api/rooms.html#room-details-api>`_",
"`Room Members API <https://element-hq.github.io/synapse/latest/admin_api/rooms.html#room-members-api>`_",
"`Room State API <https://element-hq.github.io/synapse/latest/admin_api/rooms.html#room-state-api>`_",
"`Room Messages API <https://element-hq.github.io/synapse/latest/admin_api/rooms.html#room-messages-api>`_",
"`Room Timestamp to Event API <https://element-hq.github.io/synapse/latest/admin_api/rooms.html#room-timestamp-to-event-api>`_",
"`Block Room API <https://element-hq.github.io/synapse/latest/admin_api/rooms.html#block-room-api>`_",
"|indent| `Block or unblock a room <https://element-hq.github.io/synapse/latest/admin_api/rooms.html#block-or-unblock-a-room>`_",
"|indent| `Get block status <https://element-hq.github.io/synapse/latest/admin_api/rooms.html#get-block-status>`_",
"`Delete Room API <https://element-hq.github.io/synapse/latest/admin_api/rooms.html#delete-room-api>`_",
"|indent| `Version 1 (old version) <https://element-hq.github.io/synapse/latest/admin_api/rooms.html#version-1-old-version>`_",
"|indent| `Version 2 (new version) <https://element-hq.github.io/synapse/latest/admin_api/rooms.html#version-2-new-version>`_",
"|indent| `Status of deleting rooms <https://element-hq.github.io/synapse/latest/admin_api/rooms.html#status-of-deleting-rooms>`_",
"|indent| |indent| `Query by room_id <https://element-hq.github.io/synapse/latest/admin_api/rooms.html#query-by-room_id>`_",
"|indent| |indent| `Query by delete_id <https://element-hq.github.io/synapse/latest/admin_api/rooms.html#query-by-delete_id>`_",
"|indent| |indent| `Response <https://element-hq.github.io/synapse/latest/admin_api/rooms.html#response>`_",
"|indent| `Undoing room deletions <https://element-hq.github.io/synapse/latest/admin_api/rooms.html#undoing-room-deletions>`_",
"`Make Room Admin API <https://element-hq.github.io/synapse/latest/admin_api/rooms.html#make-room-admin-api>`_",
"`Forward Extremities Admin API <https://element-hq.github.io/synapse/latest/admin_api/rooms.html#forward-extremities-admin-api>`_",
"|indent| `Check for forward extremities <https://element-hq.github.io/synapse/latest/admin_api/rooms.html#check-for-forward-extremities>`_",
"|indent| `Deleting forward extremities <https://element-hq.github.io/synapse/latest/admin_api/rooms.html#deleting-forward-extremities>`_",
"`Event Context API <https://element-hq.github.io/synapse/latest/admin_api/rooms.html#event-context-api>`_",

or with the debug output mode:

h1: Synapse



h1: List Room API
Element text:	List Room API
Link/Anchor:	#list-room-api
Indentations:	0


h1: Room Details API
Element text:	Room Details API
Link/Anchor:	#room-details-api
Indentations:	0


h1: Room Members API
Element text:	Room Members API
Link/Anchor:	#room-members-api
Indentations:	0

h1: Room State API
Element text:	Room State API
Link/Anchor:	#room-state-api
Indentations:	0

h1: Room Messages API
Element text:	Room Messages API
Link/Anchor:	#room-messages-api
Indentations:	0




h1: Room Timestamp to Event API
Element text:	Room Timestamp to Event API
Link/Anchor:	#room-timestamp-to-event-api
Indentations:	0

h1: Block Room API
Element text:	Block Room API
Link/Anchor:	#block-room-api
Indentations:	0

h2: Block or unblock a room
Element text:	Block or unblock a room
Link/Anchor:	#block-or-unblock-a-room
Indentations:	1

h2: Get block status
Element text:	Get block status
Link/Anchor:	#get-block-status
Indentations:	1

h1: Delete Room API
Element text:	Delete Room API
Link/Anchor:	#delete-room-api
Indentations:	0


h2: Version 1 (old version)
Element text:	Version 1 (old version)
Link/Anchor:	#version-1-old-version
Indentations:	1


h2: Version 2 (new version)
Element text:	Version 2 (new version)
Link/Anchor:	#version-2-new-version
Indentations:	1


h2: Status of deleting rooms
Element text:	Status of deleting rooms
Link/Anchor:	#status-of-deleting-rooms
Indentations:	1

h3: Query by room_id
Element text:	Query by room_id
Link/Anchor:	#query-by-room_id
Indentations:	2

h3: Query by delete_id
Element text:	Query by delete_id
Link/Anchor:	#query-by-delete_id
Indentations:	2

h3: Response
Element text:	Response
Link/Anchor:	#response
Indentations:	2

h2: Undoing room deletions
Element text:	Undoing room deletions
Link/Anchor:	#undoing-room-deletions
Indentations:	1


h1: Make Room Admin API
Element text:	Make Room Admin API
Link/Anchor:	#make-room-admin-api
Indentations:	0

h1: Forward Extremities Admin API
Element text:	Forward Extremities Admin API
Link/Anchor:	#forward-extremities-admin-api
Indentations:	0


h2: Check for forward extremities
Element text:	Check for forward extremities
Link/Anchor:	#check-for-forward-extremities
Indentations:	1

h2: Deleting forward extremities
Element text:	Deleting forward extremities
Link/Anchor:	#deleting-forward-extremities
Indentations:	1


h1: Event Context API
Element text:	Event Context API
Link/Anchor:	#event-context-api
Indentations:	0

@JOJ0
Copy link
Owner

JOJ0 commented Oct 19, 2024 •
edited
Loading

All docs changes are fine for me and appreciated. For me it now approves. Do you agree with my code changes too or just no time to look at them right now? @JacksonChen666

@JOJ0 JOJ0 merged commit ee412b3 into master Oct 25, 2024
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@JOJ0 JOJ0 JOJ0 approved these changes

Assignees
No one assigned
Labels
documentation Improvements or additions to documentation
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
2 participants
@JacksonChen666 @JOJ0