Links to Documentation from README / long_description

[orenbenkiki]

I have just tried to upload a new version of one of my projects and encountered the The project's long_description has invalid markup which will not be rendered on PyPI error.

Great! It is very useful to know that the README will be properly rendered and displayed in PyPI. Verifying it as a precondition for an upload is a good idea.

My current README contains :py:func:, :py:attr:, :py:class:, ... links to the generated documentation. This works great when viewing the README on readthedocs.io. Of course, it looks horrible on PyPI. So I get why these are flagged as an error, and should be fixed.

But that said... shouldn't the README / long description be able to link into the documentation? In fact, shouldn't this be encouraged?

I currently just load the README file into the long description field to avoid duplication. A quick workaround I am using for now is applying a regexp to strip away all :py:...: annotations from the long_description_field. This works of course...

Would applying such a regexp make sense as a default behavior? This would make the issue a feature request.

If this does not make sense, what is the recommended structure for a project to be properly documented in both PyPI and ReadTheDocs? Perhaps my original sin is equating the README and the long description in the first place? Are there different recommendations about what should go in each?

With the rapid (positive!) evolution of the structure of a well-behaved Python project in the past few years, it seems difficult to find a good up-to-date template of a project structure to follow. Is there a good link you could recommend?

[di]

Thanks for the feature request. I'm going to move this issue to pypa/readme_renderer where it's more appropriate, as twine is just using readme_renderer here for the check.

[wesinator]

With the rapid (positive!) evolution of the structure of a well-behaved Python project in the past few years, it seems difficult to find a good up-to-date template of a project structure to follow. Is there a good link you could recommend?

@orenbenkiki take a look at https://gitlab.com/fhightower-templates/python-project-template

[di]

Sorry, I missed that question. There's also https://github.com/pypa/sampleproject/