jsonschema deserves a ✨fancy✨ readme

[hynek]

So this is a simple starting point.

LMK what you think. I for one would probably cut "Running the Test Suite", "Benchmarks", and "Community" from PyPI.

You can test the output by checking this branch out and running pipx run hatch-fancy-pypi-readme.

---

Small aside: One thing I've notices is that your heading chars are a bit off. Your Readme uses over-and-under = but the sections use -. Then your index.rst uses - for Contents, but = for Indices and tables.

I think you should switch Contents and everything that is - in the README to just-under = and am happy to make it part of this PR if you want to.

[Julian]

Hooray! Thank you! Fancyyyyy.

Small aside: One thing I've notices is that your heading chars are a bit off. Your Readme uses over-and-under = but the sections use -. Then your index.rst uses - for Contents, but = for Indices and tables.

I think you should switch Contents and everything that is - in the README to just-under = and am happy to make it part of this PR if you want to.

This is mostly to do with the include -- making the first heading be an H1 was definitely intentional (which is why nothing else uses = over and under), but whether the index.rst uses = for Indices I don't remember whether I did on purpose or not. With your suggestion though everything would become an H3 underneath the About section no? The include doesn't do anything "smart" IIRC about re-underlining headings.

[hynek]

The h3 stuff is just relative, but this is the priority (EDIT: it is not):

==
h1
==

h2
==

h3
--

h4
~~

Since you don't have = in your README, your - become h2 when rendering it. But - clashes with your changelog.

I'm a bit surprised by both double-= and single-= becoming H1 in index.rst, I guess it's trying to be smart there?

---

Which is why I use in my docs double-= in my own docs. It makes it possible to have sections with single-= that are sometimes h1 and sometimes h2.

P.S. I hate this so much.

[hynek]

Hilariously, here's the resulting readme in a gist: https://gist.github.com/hynek/378cc636308aa9fdd9eaaea550d31e12

for some reason it made double-= h2s but I suspect that is because it has its own h1 and tries to avoid having two.

[Julian]

I'm a bit surprised by both double-= and single-= becoming H1 in index.rst, I guess it's trying to be smart there?

Those are different, double-= becomes H1, and single-= becomes H3, see: https://python-jsonschema.readthedocs.io/en/stable/#jsonschema vs. https://python-jsonschema.readthedocs.io/en/stable/#indices-and-tables

The priority is based on what heading styles it sees first

EDIT: Oops, hit send by accident, no matter -- but yeah basically include is the weird thing here, and I'm not sure what to do about the CHANGELOG but possibly this is a feature the fancy readme generator should have no? Renumbering headings? E.g. in markdown you can do this, but rst is.. annoying.

[hynek]

ugh yeah you're right…it's about order which is insane.

just to re-iterate: the problem is that the changelog uses the same section marker as the readme. pulling it up to = would solve it, because "Release Info" could become single-=.

There's almost nothing in the index.rst: we'd just have to switch the marker of Contents and Indices, or am I missing something again?

[Julian]

There's a bunch of ways to do it, I think the easiest one is to leave index.rst exactly as is (so its sections stay H2 and H3 respectively) and then make Release Information single-- which would be H2, and then change all the headings in the Changelog to = which would make them H3 (under the release information).

[ssbarnea]

TBH, I by fancy it means potential (ab)use of emoji, like in PR title, I would better prefer it without it. I hate seeing emoji inside commit messages, makes the git log looks my Spam folder from gmail.

Emoji are fine, for personal messages but not for changelogs. They distract user from the real content.

[hynek]

There's a bunch of ways to do it, I think the easiest one is to leave index.rst exactly as is (so its sections stay H2 and H3 respectively) and then make Release Information single-- which would be H2, and then change all the headings in the Changelog to = which would make them H3 (under the release information).

Done!

I've updated https://gist.github.com/hynek/378cc636308aa9fdd9eaaea550d31e12 for preview too.

[codecov-commenter]

Codecov Report

Merging #983 (66223a2) into main (0c4aaaf) will increase coverage by 0.01%.
The diff coverage is n/a.

@@            Coverage Diff             @@
##             main     #983      +/-   ##
==========================================
+ Coverage   98.18%   98.19%   +0.01%     
==========================================
  Files          20       20              
  Lines        3307     3326      +19     
  Branches      529      531       +2     
==========================================
+ Hits         3247     3266      +19     
  Misses         46       46              
  Partials       14       14              

Impacted Files	Coverage Δ
jsonschema/validators.py	96.69% <0.00%> (+0.01%)	⬆️
jsonschema/tests/test_validators.py	98.96% <0.00%> (+0.01%)	⬆️

Help us with your feedback. Take ten seconds to tell us how you rate us. Have a feature suggestion? Share it here.

[Julian]

Hooray! Thanks :D, very fancy.