Dbal: [Doc] Mapping matrix documentation is broken

[magnetik]

Bug Report

Check https://www.doctrine-project.org/projects/doctrine-dbal/en/2.8/reference/types.html#mapping-matrix

Summary

The mapping matrix is all broken.

Current behaviour

It super unreadable.

How to reproduce

Go to https://www.doctrine-project.org/projects/doctrine-dbal/en/2.8/reference/types.html#mapping-matrix

Expected behaviour

A nice clean table

[jwage]

This is due to this issue https://github.com/doctrine/rst-parser/issues/38

[francescolaffi]

in case someone find this issue by searching for a solution: as a temporary workaround the table is rendered correctly by github https://github.com/doctrine/dbal/blob/2.9/docs/en/reference/types.rst

[jwage]

This will be fixed soon thanks to @weaverryan. He enhanced the underlying rst parser in https://github.com/doctrine/rst-parser/pull/100 andhttps://github.com/doctrine/rst-parser/pull/110

I just need to release a new version and upgrade the website now.

[Jamesking56]

Any updates @jwage ?

[jwage]

The enhancement have been merged to doctrine/rst-parser but I still need to make a new release and then upgrade the website.

[skillbox-koutja]

Matrix is still broken?!

[ro0NL]

~wow. No need for an issue i guess... :disappointed:~

friendly ping :)

[greg0ire]

People, please, there are nicer ways to do this. @jwage can you please proceed with the release and the update, or tell us how we can help moving this forward?

[SenseException]

I'm working on a few changes and updates for the website that also need some updates on the side of doctrine/rst-parser. If a release is the only thing that needs to be done, I'll do one. Before that, I'll check the current state of doctrine/rst-parser for the table changes.

[SenseException]

In TableNode.php line 447: Cannot find column for index "%s"

I get this error when I try to build the dbal-docs with the master branch of doctrine/rst-parser.

Plus: doctrine/rst-parser is also a dependency of doctrine/static-website-generator which is why this package needs to be updated at least with the newest version of the rst-parser. Looks like this will take more time.

[SenseException]

| **binary**        | ``resource``  | **MySQL**                | *all*   | ``VARBINARY(n)`` [3]_                                    |
| [2]_ [6]_         |               +--------------------------+         |                                                          |
|                   |               | **SQL Server**           |         +----------------------------------------------------------+
|                   |               +--------------------------+         | ``BINARY(n)`` [4]_                                       |
|                   |               | **Oracle**               | *all*   | ``RAW(n)``                                               |
|                   |               +--------------------------+---------+----------------------------------------------------------+

The implementation in doctrine/rst-parser master is having trouble with the last column and the third column. The fourth one is having a span of three on the left side and two on the right. In other parts of the table it looks like this:

| **string**        | ``string``    | **MySQL**                | *all*   | ``VARCHAR(n)`` [3]_                                      |
| [2]_ [5]_         |               +--------------------------+         |                                                          |
|                   |               | **PostgreSQL**           |         |                                                          |
|                   |               +--------------------------+         +----------------------------------------------------------+
|                   |               | **SQLite**               |         |                                                          |
|                   |               +--------------------------+---------+----------------------------------------------------------+

and the rst-parser can handle this format.

To be able to handle a rst-table like in the first example, the rst-parser implementation for tables has to be much more complex ~and the current complexity isn't covered with tests yet for unknown reason~.

@greg0ire How should we proceed here? There's currently no working table rendering that creates a readable table in the docs. So one suggestion is to adapt the rst-table for binary to match the second example and make a release of the current rst-parser master.

• The advantage would be a readable documentation.
• The disadvantage is that a messed up rst-table would be noticed pretty late: In a breaking documentation build in the doctrine-website CI.

Maybe the website should use a different rst-library in the future for the documentation build.

[greg0ire]

How should we proceed here?

Let's go with your suggestion

Maybe the website should use a different rst-library in the future for the documentation build.

Maybe we should have a build per library for validating changes to the docs too… that would fix the disadvantage you pointed out.

[SenseException]

I found out that this would also need changes in the documentation of version-branches, that aren't supported anymore. The mapping matrix was also in older versions available.