docs: Clean up check-build.sh
docs: Clean up check-build.sh

Various miscellaneous clean-up and improvements:

- Remove the previous warnings.txt file before running the script, to
  avoid printing outdated messages

- Attempt to clean up the calls to sphinx-build: do not redirect into
  tee, only use the warnings.txt file for printing warnings. This makes
  the script easier to understand.

- Rework some options passed to shpinx-build.
    - Use "--color" to have colors, even if the warnings are printed to
      a file, so we can later dump them with colors.
    - Use "-n" to tell sphinx-build to be nitpicky when reporting
      errors; this does not raise any additional warning at this time.
    - Use "-W --keep-going" for checks so we can rely on the exit status
      of the command (which does not break the script, because it's
      called inside of a "if" through build_with_spellchecker()).
    - Do NOT pass "-E" if we run all the checks. The checks re-read all
      files already; there is no reason to read them all again when
      building the final version.

- Add a note on the apparent non-feasability to call sphinx only once,
  even if moving the script to Python

- Rework a bit the file, by moving the call to rstcheck to a dedicated
  function

- Add some comments for various functions/invocations

- Add function cat_warnings(), which doesn't look very useful but will
  be reused to reintroduce filters on warnings.

Note: I also wanted to pass "-j auto" to sphinx-build in order to enable
parallel builds, but on some setups (macOS M1) this produced warnings
about duplicated declarations of HTTP methods when generating the API
documentation through the openapi extension (which in turns rely on
httpdomain) - see [0].

[0] https://github.com/sphinx-contrib/httpdomain/commit/b00105a884639504d7d079238e221290785a66d0#diff-ee3c6c3e25cffc74b15c05f2b6c0e72c8d29d9de8fb5c8a51309fb45c102e9e4R710

Signed-off-by: Quentin Monnet <d6b8e48afb2534b213e391cab43016505747a234@isovalent.com>

michi-covalent/cilium,cilium/cilium,cilium/cilium,michi-covalent/cilium,cilium/cilium,cilium/cilium,cilium/cilium,michi-covalent/cilium,michi-covalent/cilium,michi-covalent/cilium