search

element-hq / synapse

Synapse: Matrix homeserver written in Python/Twisted.
https://element-hq.github.io/synapse
GNU Affero General Public License v3.0
963 stars 109 forks source link

Fixes to the table of contents in the README #17329

Closed anoadragon453 closed 6 days ago

anoadragon453 commented 1 week ago

With the top-level header, the auto-generated TOC is pretty ugly.

image

We could manually write a TOC, but we'd need to keep it up to date.

GitHub generates a TOC already - just hit the Outline button:

image

I propose to just remove it. Let's fix it: https://github.com/element-hq/synapse/pull/17329#issuecomment-2182617839

(Note that this is probably the only thing holding us back from converting the README to markdown - but that would be a separate PR.)

erikjohnston commented 1 week ago

Can we not remove the === from below the image so its not a header?

reivilibre commented 1 week ago

why is the Installation section under the Subscription section anyway? That is a bug in both TOCs.

Is it time to accept that the days of rST are over and switch to Markdown? Honestly I don't know the header syntax for rST but I guess we screwed up the levels here

anoadragon453 commented 1 week ago

Can we not remove the === from below the image so its not a header?

We can, and that does improve the look of the ToC:

image

But the header looks worse off for it:

image

Although we can make it look a bit better with the following:

**Element Synapse - Matrix homeserver implementation**

|support| |development| |documentation| |license| |pypi| |python|

image

why is the Installation section under the Subscription section anyway? That is a bug in both TOCs.

Looks like we can fix that by using ===s under the "Subscription alternative" header instead:

image

I still don't like the bare "Contents" text above the ToC, preferring a bold "Table of Contents". But it doesn't look like GitHub's RST renderer supports the :title: option for .. contents::.

I suppose with those changes, the ToC works and looks alright. Should we keep it then with those changes?