Injection of interferes with documentation generator

echedey-ls

Sphinx is a documentation generation environment widely used. For example, a table can be rendered using:

.. csv-table:: Title
   :file: ./foo.csv
   :class: sphinx-datatable
   :widths: 10,5,50,5,25,5
   :header-rows: 1

where the input information comes from a CSV file. Other "directives" (like csv-table) also exist to generate tables. See this
As can be seen above, it allows a :widths: option, with the percentage each column should span.

When specified, it will add a custom <colgroup> to the table. Since DataTables v2.0.0, this node is also injected by default. Is there any way to turn it off, so as to avoid node duplication? As of now, DataTables node interferes with the Sphinx one.

We found a problem when including DataTables into Sphinx-rendered docs at https://github.com/sharm294/sphinx-datatables/issues/13, a Sphinx extension plugin that eases bundling DataTables.

Relevant forum post: https://datatables.net/forums/discussion/78311/no-longer-able-to-include-our-own-colgroup-tag-in-2-0-0

Users can also stop specifying the :widths:, but I guess some use cases may still like to use it.

echedey-ls

This is the correct GitHub issue link: https://github.com/sharm294/sphinx-datatables/issues/13 (no trailing comma)

allan

Hi,

Unfortunately no, at the moment there isn't an option for this. What I could do perhaps, is remove any pre-exiting colgroup elements (or emptying and then reusing it).

When doing that work on 2.0 originally I did look into trying to merge an existing colgroup with my own, but it was going to be a signifiant amount of code for something that was (in my experience) rarely used.

Would you be happy with a simple removal / replacement?

Allan

echedey-ls

Thanks Allan for the fast response (and sorry for my late one!).

I think the second optimal solution would be to have a DataTables option to disable automatic colgroup injection.
I understand DataTables v2 injects it to make the header fit well - that's why some users may have had to set their own widths with DataTables v1. Looks handy (and optimal) but this injection is a breaking change for some users.

My best idea would be to inject colgroup only if there isn't a previous colgroup node present. That wouldn't require any changes for us nor the users, and doesn't add much complexity to your codebase if I don't misunderstand the scope (and my knowledge is enough).

I don't think a removal & replace would be very useful, but it is an option. Maybe all these three possibilities could be implemented in an option like colgroup_injection[_mode] that can be set to:
1. Current behaviour: replace-if-exists / if-present-override / always
2. Compat with user-provided config, only if provided: keep-if-exists / if-present-keep / if-not-present
3. DataTables v1 behaviour: do-not-add / no / none / false / never

Just throwing some ideas in case you find them useful. Please let me know if I can assist with anything.

allan

DataTables needs the colgroup and col tags in order to have any hope of getting the column widths correct. If the source colgroup has a single col per column, then a merge would be easy. Is that always the case with Sphinx?

I'm wondering if I should try and do that, but if a colspan is found, throw it away and use DataTables own. It would of course be possible to code for that, but it is so rarely used I don't wish to add a couple of extra KB to the library to support it. It isn't ideal, but that might be a good balance.

Allan

echedey-ls

Sphinx only creates colgroup with one level of col tags if the user wishes, by specifying the :widths: option. So, in general, Sphinx users don't have a colgroup. Only some of them have tables created with the :widths: options, and just a small group also use DataTables (either directly or via the linked extension).

This is the HTML colgroup original output from Sphinx when the table directive is configured with :widths: 10,5,50,5,25,5, which would generate one col per table column. Misconfigured length of :widths: raise an error.

<colgroup>
  <col style="width: 10.0%">
  <col style="width: 5.0%">
  <col style="width: 50.0%">
  <col style="width: 5.0%">
  <col style="width: 25.0%">
  <col style="width: 5.0%">
</colgroup>

DataTables needs the colgroup and col tags in order to have any hope of getting the column widths correct.

I was afraid DataTables used them for something else too. So, confirmed this, I think I should just add an admonition so users don't rely on Sphinx :widths: when creating their table, but rather use the width feature already provided in DataTables v2. Sadly, it still is a breaking change.

Honestly, I wouldn't bother trying to merge the configurations. Either substitute or do not add look good to me.

Would you be happy with a simple removal / replacement?

Yes. A plain remove what previously was there / add what DataTables v2 calculates would be enough, IMO.

Thanks for your help, Allan.

Echedey.

allan

Hi Echedey,

Thanks for your reply and extra information! What I've done is to commit this change which will remove any existing colgroup elements during the initialisation, before DataTables inserts its own.

That isn't ideal - it means that the assigned widths from Sphinx are going to be thrown away by DataTable, but it will at least allow the table to work. It somewhat side steps the issues with colspan and other complexities as well.

Regards,
Allan

echedey-ls

Looks good to me
Thanks a lot, Allan!