Excerpts from Akihiro Motoki's message of 2018-06-06 16:36:45 +0900: > Hi the release team, > > When I prepared neutron Rocky-2 deliverables, I noticed a new metadata > syntax check > which checks README.rst was introduced. > > As of now, README.rst in networking-bagpipe and networking-ovn hit this [1]. > > Although they can be fixed in individual projects, what is the current > recommended solution? > > In addition, unfortunately such checks are not run in project gate, > so there is no way to detect in advance. > I think we need a way to check this when a change is made > instead of detecting an error when a release patch is proposed. > > Thanks, > Akihiro (amotoki) > > [1] > http://logs.openstack.org/66/572666/1/check/openstack-tox-validate/b5dde2f/job-output.txt.gz#_2018-06-06_04_09_16_067790
I apologize for not following through with more communication when we added this check. We started noticing uploads to PyPI fail because of validation errors in the README.rst files associated with the packages. We think this is a recent change to warehouse (the software that implements PyPI). The new check in the releases repo validation job tries to catch the errors before the upload fails, so they can be fixed. We wanted to start by putting it in the releases repo because it would only block releases, and not block projects from landing other patches. I recommend that projects update their tox.ini to modify their pep8 or linters target (whichever you are using) to add this command: python setup.py check --restructuredtext --strict For the check to run, the 'docutils' package must be installed, so you may have to add that to the test-requirements.txt list. Be forewarned that the error messages can be scant, almost to the point of useless. In some cases the exception has to do with implementation details of the parser, rather than explaining what part of the input triggered the error. Usually the problems are caused by using RST directives that are part of Sphinx but not "core" RST in the README.rst ("code-block" is a common one). If you can't figure out what's wrong, please post a link to the README.rst on the mailing list or in #openstack-docs and someone will try to help you out. Doug __________________________________________________________________________ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev