Open Stack

On 06/06/2018 11:35 AM, Jeremy Stanley wrote:
> On 2018-06-06 18:24:00 +0200 (+0200), Dmitry Tantsur wrote:
>> In Ironic world we run doc8 on README.rst as part of the pep8 job.
>> Maybe we should make it a common practice?
> [...]
>
> First, the doc8 tool should be considered generally useful for any
> project with Sphinx-based documentation, regardless of whether it's
> a Python project. Second, doc8 isn't going to necessarily turn up
> the same errors as `python setup.py check --restructuredtext
> --strict` since the latter is focused on validating that the
> long description (which _might_ be in a file referenced from your
> documentation tree, but also might not!) for your Python package is
> suitable for rendering on PyPI.

This is a good point about the README not necessarily being the
long description. Another option for teams that have complicated
README files that would be a lot of work to make compatible would
be to explicitly set the long_description value for the project to
something else:

https://pythonhosted.org/an_example_pypi_project/setuptools.html