Tools: Rucio-Processor for markdown allows dark mode tables

The pipeline for the creation of the rucio-docs for the client API is as
follows:

* begin process using `build_documentation.sh`
* `generate_dynamic_files.sh` spins up a docker container
* inside of the docker container, `generate_docs.sh` is called
* which in turn calls `generate_client_api_docs.sh`
* `generate_client_api_docs.sh` parses the files in `lib/rucio/client`
  and converts them using `pydoc-markdown`.
* `pydoc-markdown` uses `rucio_processor.py` and `rucio_renderer.py`
  (both in `tools/run_in_docker`, which is mounted into the docker
  container).
* "auto_generated" output markdown files' ownerships are changed
* compiling this markdown into html -> completed using docusaurus as
  part of the github action

The final stage adds styling (i.e. CSS) to the compiled markdown files.
This means that in general, a dark mode can be applied. However, some
components in the client api are formatted in pre-styled HTML tables
(within the markdown!), these styles are never overridden.

As discussed with @bari12, a simple fix to the missing dark mode is
proposed here. Instead of reworking the markdown to use plain
markdown-tables which are styled at the appropriate (docusaurus) step
(and not HTML tables that come with their own style), we reference a
docusaurus CSS variable `--ifm-background-color`, which will set the
correct dark mode colour (depending on whether dark or light mode is
requested).

We are aware of the fact that in doing so, we reference a variable
several steps before it is defined. In addition, we add even more
complicated HTML/CSS syntax to markdown, which is supposed to be easy on
human eyes. The benefit of this fix is that it is minimally-invasive,
and that the markdown files are never supposed to be served by
themselves and only act as a middle step for the entire pipeline.

Author: Anton Schwarz

tools/README.md

@@ -31,6 +31,31 @@ flowchart TD
 	rest_api_docs-->rest_api_docs_html[Generate Rest Api Docs Html]
 ```
 
+Following this, a Github Action calls `yarn build`, which runs docusaurus (the
+tool which takes the markdown files and converts them into HTML)
+
+### Building the Docs for the Client API
+The pipeline for the creation of the rucio-docs for the client API is as
+follows:
+
+* begin process using `build_documentation.sh`
+* `generate_dynamic_files.sh` spins up a docker container
+* inside of the docker container, `generate_docs.sh` is called
+* which in turn calls `generate_client_api_docs.sh`
+* `generate_client_api_docs.sh` parses the files in `lib/rucio/client`
+  and converts them using `pydoc-markdown`.
+* `pydoc-markdown` uses `rucio_processor.py` and `rucio_renderer.py`
+  (both in `tools/run_in_docker`, which is mounted into the docker
+  container).
+* "auto_generated" output markdown files' ownerships are changed
+* compiling this markdown into html -> completed using docusaurus as
+  part of the github action
+
+The final stage adds styling (i.e. CSS) to the compiled markdown files.
+This means that in general, a dark mode can be applied. However, some
+components in the client api are formatted in pre-styled HTML tables
+(within the markdown!), these styles are never overridden.
+
 ## Check Repository Health
 
 The repository has several scripts to check the health of files. These include:

tools/run_in_docker/rucio_processor.py

@@ -64,13 +64,13 @@ def generate_sections_markdown(sections):
             ret.append("\n<tr style={{border: 'none'}}>\n")
 
             ret.append(
-                "\n<td style={{border: 'none', backgroundColor: 'white', 'verticalAlign': 'top'}}>\n"  # noqa: E501
+                "\n<td style={{border: 'none', backgroundColor: 'var(--ifm-background-color)', 'verticalAlign': 'top'}}>\n"  # noqa: E501
             )
             ret.append(f"**{key}**:")
             ret.append("\n</td>\n")
 
             ret.append(
-                "\n<td style={{border: 'none', backgroundColor: 'white', 'verticalAlign': 'top'}}>\n"  # noqa: E501
+                "\n<td style={{border: 'none', backgroundColor: 'var(--ifm-background-color)', 'verticalAlign': 'top'}}>\n"  # noqa: E501
             )
             ret.extend(section)
             ret.append("\n</td>\n")