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.

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

jsonschema deserves a ✨fancy✨ readme #983

Merged
merged 3 commits into from
Aug 18, 2022
Merged

jsonschema deserves a ✨fancy✨ readme #983

merged 3 commits into from
Aug 18, 2022

Conversation

hynek
Copy link
Contributor

@hynek hynek commented Aug 17, 2022

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
Copy link
Member

Julian commented Aug 17, 2022

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.

pyproject.toml Outdated Show resolved Hide resolved
@hynek
Copy link
Contributor Author

hynek commented Aug 17, 2022

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
Copy link
Contributor Author

hynek commented Aug 17, 2022

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
Copy link
Member

Julian commented Aug 17, 2022

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
Copy link
Contributor Author

hynek commented Aug 17, 2022

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
Copy link
Member

Julian commented Aug 17, 2022

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
Copy link
Contributor

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
Copy link
Contributor Author

hynek commented Aug 18, 2022

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
Copy link

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
Copy link
Member

Julian commented Aug 18, 2022

Hooray! Thanks :D, very fancy.

@Julian Julian merged commit 90f7d20 into python-jsonschema:main Aug 18, 2022
Julian added a commit that referenced this pull request Aug 18, 2022
@hynek hynek deleted the fancy-sparkles branch August 18, 2022 08:49
sigprof added a commit to sigprof/nix-devenv-qmk that referenced this pull request Aug 20, 2022
The `jsonschema` module uses `hatch-fancy-pypi-readme` for build since
version 4.11.0 (python-jsonschema/jsonschema#983); add that module to
the `[tool.poetry.dev-dependencies]` section in `pyproject.toml`, so
that it would be available for the upcoming poetry2nix override.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants