Support header_rows in ascii.rst (reStructuredText) writer [swev-id: astropy__astropy-14182]

[casey-brooks]

Observed failure

ascii.rst currently rejects the header_rows keyword:

Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/usr/lib/python3/dist-packages/astropy/table/connect.py", line 129, in __call__
    self.registry.write(instance, *args, **kwargs)
  File "/usr/lib/python3/dist-packages/astropy/io/registry/core.py", line 369, in write
    return writer(data, *args, **kwargs)
  File "/usr/lib/python3/dist-packages/astropy/io/ascii/connect.py", line 26, in io_write
    return write(table, filename, **kwargs)
  File "/usr/lib/python3/dist-packages/astropy/io/ascii/ui.py", line 856, in write
    writer = get_writer(Writer=Writer, fast_writer=fast_writer, **kwargs)
  File "/usr/lib/python3/dist-packages/astropy/io/ascii/ui.py", line 800, in get_writer
    writer = core._get_writer(Writer, fast_writer, **kwargs)
  File "/usr/lib/python3/dist-packages/astropy/io/ascii/core.py", line 1719, in _get_writer
    writer = Writer(**writer_kwargs)
TypeError: RST.__init__() got an unexpected keyword argument 'header_rows'

Reproduction

from astropy.table import QTable
import astropy.units as u
import sys

tbl = QTable({'wave': [350, 950] * u.nm, 'response': [0.7, 1.2] * u.count})
tbl.write(sys.stdout, format="ascii.rst", header_rows=["name", "unit"])

See #118 for the full context.

Summary

• allow RST to forward header_rows into FixedWidth and derive the separator line from the header row count
• extend the regression suite with header-row scenarios (units, missing units, unicode, masked values, and default behavior)
• document header_rows support for ascii.rst in the fixed-width gallery

Testing

• pytest astropy/io/ascii/tests/test_rst.py --maxfail=1 --disable-warnings -q
• pytest astropy/io/ascii/tests/test_fixedwidth.py --maxfail=1 --disable-warnings -q
• isort astropy/io/ascii/rst.py astropy/io/ascii/tests/test_rst.py
• pyupgrade --py38-plus astropy/io/ascii/rst.py astropy/io/ascii/tests/test_rst.py
• flake8 astropy/io/ascii/rst.py astropy/io/ascii/tests/test_rst.py

[casey-brooks]

Test & Lint Summary

• pytest astropy/io/ascii/tests/test_rst.py --maxfail=1 --disable-warnings -q (14 passed)
• pytest astropy/io/ascii/tests/test_fixedwidth.py --maxfail=1 --disable-warnings -q (35 passed)
• isort astropy/io/ascii/rst.py astropy/io/ascii/tests/test_rst.py
• pyupgrade --py38-plus astropy/io/ascii/rst.py astropy/io/ascii/tests/test_rst.py
• flake8 astropy/io/ascii/rst.py astropy/io/ascii/tests/test_rst.py (no issues)

tox -e codestyle currently fails while provisioning the isort pre-commit hook, so I ran the repo's manual lint commands instead.

[noa-lucent]

Looks great. Thanks!