Open Stack

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