I’m trying to publish a package to Pypi using github actions, which apparently uses “twile” or something.
Trying to publish it fails because it detects an error at line 25 of my readme file for incorrect indentation. In fact it is not a mistake, since github renders it correctly and any other identation at that line yields a very different result.
I tried the verify-metadata: false option in the toml file, thinking that only twile’s checker was wrong, but it gave me a 400 Bad Request from https://upload.pypi.org/legacy/ The description failed to render for 'text/x-rst'. See https://pypi.org/help/#description-content-type for more information., so Pypi also fails to recognize that syntax.
I tried removing the readme line in the toml file, but that gave another error ``long_description has syntax errors in markup and would not be rendered on PyPI. No content rendered from RST source.
How can I upload my package to pypi, with or without readme ?
The Readme can be RST or Markdown, it should work, if it’s valid. You’ll find RST validators on PyPI, but you could use something like Pandoc if you wish to convert between formats.
There is a guide here on how to make a PyPI friendly README.
I think this in particular could be useful - a way to locally check whether your README will render on PyPI:
To locally check whether your long descriptions will render on PyPI, first build your distributions, and then use the twine check_ command.
So you could install twine and run that against your README.
I read that, but it doesn’t contain syntax-specific advice relevant to my issue.
The goal is to publish my package from github directly. And assuming twine is what’s used by github actions, what information would a check run locally give me, except that it fails on line 25 ?
What I need is for pypi to recognize that syntax as valid, as it is and as Github does.
Perhaps it is a problem with the GitHub Action. Which GitHub Action are you referring to? As described on the PyPI guide for READMEs, valid formats for the README are plain text, RST without Sphinx extensions, or GitHub flavored Markdown. That’s why I suggested Pandoc - you can take your RST, convert it to GitHub flavored MD, and see if that raises the same or similar error.
P. S. I had some issues with RST READMEs in one of my packages, and partly because of that I converted the README to Markdown.
reStructuredText is picky about blank lines around lists. If you want to create a sublist, you need to insert blank lines immediately before and after the sublist.
So, rst considers this to be incorrect:
- The seats will placed in rows, such that:
- The rows are semicircular arcs concentric to the inner and outer arcs.
While this would be correct:
- The seats will placed in rows, such that:
- The rows are semicircular arcs concentric to the inner and outer arcs.
Some rst implementations are ok with text that bends the rules a bit, which is probably why it renders ok on GitHub.
Thanks ! that solved it. I just added line breaks before wrapped 2nd-degree bullet points and it worked.
Though Pypi would gain of using a more robust rst compiler, like GitHub’s seems to be.
A couple of final points on this: I was reminded of Documatt Snippets as a better alternative for previewing the RST output.If you paste your original README RST into the Write textbox and click on the Preview pane, then you should see the markup error messages in red. So those are genuine errors in the markup, not an issue with RST processor.
In relation to this comment:
Pypi would gain of using a more robust rst compiler, like GitHub’s seems to be.
it is actually the other way around: GitHub has the looser enforcement of RST syntax.
Thanks a lot, this one does work on my end and I’ll keep it.
With regard to that, it’s another way of looking at it, sure. But I don’t see how GitHub’s enforcement is worse off : it’s just as unambiguous and yields shorter documents. I don’t see a need for the strictness of the stricter standard (although we can’t consider it to be faulty, sure).
The answer is to go back to the source, in this case the RST markup spec., specifically on blank lines and indentation. That should make it clear why the GitHub RST rendering isn’t quite correct, or at least why we should consider it at such.
I understand that, but since the way github does it is consistent, intuitive and unambiguous, I don’t see why upgrading the spec wouldn’t be the best course forward.
I can’t comment generally on the GitHub component that processes RST, but my point here is that with respect to the rendering of that sublist-in-a-list excerpt from your original README GitHub was not consistent with the RST spec. In that version the sublist within a list wasn’t separated by a newline and so was treated by PyPI RST as paragraph continuation - the RST spec is clear that there should have been a newline preceding the sublist.
In this case, the specific “source of truth” is the readme-renderer · PyPI library, since that’s what
PyPI (Warehouse) and twine are using to validate the
long_description content, which in turn relies on the docutils
module from the CPython stdlib for reStructuredText parsing.
