Open Stack

Hi,

As you may notice, we see a lot of patches which try to add
--keep-going to sphinx-build. [0]
I have suggestions and questions.

1) First, when reviewing them, keep the following in your mind.

* --keep-going is added even when -W option is not used in the
sphinx-build command line.
  -W is recommended in the PTI [1], so ensure to have -W.
* Some of them ignores cases where "python setup.py build_sphinx" is still used.
   If it is a good chance to clean them up and use "sphinx-build" consistently.

2) Why do we need to remove the build directory for releasenotes?
   Some of them propose to add "rm -rf releasenotes/build"? (for example [2])
   I cannot understand why this needs to be added.
   Do we really want to call "rm -rf <build dir>"?

   I know it is needed in some repositories due to various reasons,
   but generally speaking it make the documentation build longer and
they are unnecessary.

   I tried to get the reason from the authors in reviews but they just
say it is simple and it can be added at the same time.
   Thus, I would like to ask it more broadly in the list.


3) What is the recommended way to get a consensus to make this kind of
patches which affects many many repositories?

   It is not productive to ask questions in individual reviews.
   Some patches are approved fast and questions are pop-up in other patches.
   It makes it difficult to discuss the real needs and keep many
repositories consistent.

   I am not against all of these changes, but I would like to see more
organized way.

   Thought?

Thanks,
Akihiro

[0] https://review.opendev.org/#/q/message:keeping
[1] https://governance.openstack.org/tc/reference/project-testing-interface.html#documentation
[2] https://review.opendev.org/#/c/690956/2/tox.ini