Add columns for common arguments, descriptions

[voetberg]

Partially closes #499

Rest would need to be addressed with changes to core.

[rdimaio]

LGTM, not sure what's going on with the CI

[Geogouz]

LGTM, not sure what's going on with the CI

YAML parsing problems.
We could use maybe multi-line YAML strings to avoid parser confusion?

namely for example here, go from:

description: defines how to handle datasets: `fifo` (each file released separately) or `grouped_fifo` (wait for the entire dataset to fit)

to something like:

description: |
  defines how to handle datasets: `fifo` (each file released separately)
  or `grouped_fifo` (wait for the entire dataset to fit)

[rdimaio]

LGTM, not sure what's going on with the CI

YAML parsing problems. We could use maybe multi-line YAML strings to avoid parser confusion?

namely for example here, go from:

description: defines how to handle datasets: `fifo` (each file released separately) or `grouped_fifo` (wait for the entire dataset to fit)

to something like:

description: |
  defines how to handle datasets: `fifo` (each file released separately)
  or `grouped_fifo` (wait for the entire dataset to fit)

Yeah, I think ideally it would be best to fix this on the doc generation side, rather than having to think about this whenever we write docstrings in the main code

[voetberg]

LGTM, not sure what's going on with the CI

YAML parsing problems. We could use maybe multi-line YAML strings to avoid parser confusion?
namely for example here, go from:

description: defines how to handle datasets: `fifo` (each file released separately) or `grouped_fifo` (wait for the entire dataset to fit)

to something like:

description: |
  defines how to handle datasets: `fifo` (each file released separately)
  or `grouped_fifo` (wait for the entire dataset to fit)

Yeah, I think ideally it would be best to fix this on the doc generation side, rather than having to think about this whenever we write docstrings in the main code

Ideally this should be caught by tools/check_rest_api_documentation.sh in the main repo - is there a reason that isn't run as part of the testing suite? It's use is described in our developer docs

[rdimaio]

LGTM, not sure what's going on with the CI

YAML parsing problems. We could use maybe multi-line YAML strings to avoid parser confusion?
namely for example here, go from:

description: defines how to handle datasets: `fifo` (each file released separately) or `grouped_fifo` (wait for the entire dataset to fit)

to something like:

description: |
  defines how to handle datasets: `fifo` (each file released separately)
  or `grouped_fifo` (wait for the entire dataset to fit)

Yeah, I think ideally it would be best to fix this on the doc generation side, rather than having to think about this whenever we write docstrings in the main code

Ideally this should be caught by tools/check_rest_api_documentation.sh in the main repo - is there a reason that isn't run as part of the testing suite? It's use is described in our developer docs

We could add that to the main repo's CI, but is there no way to fix this on the generation side, e.g. ignoring every colon after the first?

[Geogouz]

LGTM, not sure what's going on with the CI

YAML parsing problems. We could use maybe multi-line YAML strings to avoid parser confusion?
namely for example here, go from:

description: defines how to handle datasets: `fifo` (each file released separately) or `grouped_fifo` (wait for the entire dataset to fit)

to something like:

description: |
  defines how to handle datasets: `fifo` (each file released separately)
  or `grouped_fifo` (wait for the entire dataset to fit)

Yeah, I think ideally it would be best to fix this on the doc generation side, rather than having to think about this whenever we write docstrings in the main code

Ideally this should be caught by tools/check_rest_api_documentation.sh in the main repo - is there a reason that isn't run as part of the testing suite? It's use is described in our developer docs

We could add that to the main repo's CI, but is there no way to fix this on the generation side, e.g. ignoring every colon after the first?

We can maybe continue about it here #567