Wrong heading levels in the generated data model documentation

[vkucera]

Hi @pbuehler , could you please fix the wrong heading levels in the generated data model documentation?
See the error details in the MegaLinter log: https://github.com/AliceO2Group/analysis-framework/actions/runs/4248893181/jobs/7388526270

[pbuehler]

@vkucera @TimoWilken There are two types of errors:

1 MegaLinter complains about the headings in the md files. It seems to strictly require that a heading of level n is followed by a heading of level (n+1). I don't think we want to have such restrictions.
2 MegaLinter complains about links which can not be followed. This concerns e.g. the link https://aliceo2group.github.io/analysis-framework/docs/datamodel/ao2dTables.html#cat_General. This is an internal link and works on the on web site. But I assume that MegaLinter is not properly setup to test internal links.

Can MegaLinter be told to ignore cases 1 and distinguish between external and internal links (cases 2)?

[vkucera]

1 It is not clear to me how skipping a heading level is of any good. I suppose that fixing it is a matter of removing one # in the code.
2 The internal links are done using id= which is not the Markdown standard <a name=. I know it works on the web and that's why I did not mention those errors here but setting MegaLinter to ignore them makes the check blind to genuine broken internal links.

[pbuehler]

1. The changes would be rather minor, that is true. I'll try and see how it looks like then.

2. I can try to change the internal links to the Markdown standard. I however also have to assure that the syntax is understood by GitHub Pages, which translates the md to html. With the currently used syntax the translation works.

[vkucera]

Thanks a lot!

[pbuehler]

Hi @vkucera ,

1. I modified the code such that now the heading level order is correct. Since all headings of level 1 and 2 are automatically added to the menu of the left hand side of the documentation web pages, these changes also affect the menu - there are additional entries now. I think that is ok (but that is one of the reasons why one could want to skip a heading level).

2. This is more tricky. The mds provided to GitHub Pages are a mixture of md and html. The tables in the "data model reference appendix" are defined with html and so also the categories and the related anchors. To me it seems that this mixture of md/html is not taken into account in all details by MegaLinter. Anyway, I found a way around by switching between md and html mode for the table header/anchors and the table definitions. This provides the wanted functionality and also uses the Markdown standard for the anchors.

I'll provide a related PR soon.
Paul

[pbuehler]

By the way ...
the modification needed to include the tables of all PWGs have been provided with PR #10675 and should become effective once the documentation pages are regenerated.

[vkucera]

By the way ... the modification needed to include the tables of all PWGs have been provided with PR #10675 and should become effective once the documentation pages are regenerated.

Yes, I saw it. Thanks for that!

[vkucera]

Hi @vkucera ,

1. I modified the code such that now the heading level order is correct. Since all headings of level 1 and 2 are automatically added to the menu of the left hand side of the documentation web pages, these changes also affect the menu - there are additional entries now. I think that is ok (but that is one of the reasons why one could want to skip a heading level).

2. This is more tricky. The mds provided to GitHub Pages are a mixture of md and html. The tables in the "data model reference appendix" are defined with html and so also the categories and the related anchors. To me it seems that this mixture of md/html is not taken into account in all details by MegaLinter. Anyway, I found a way around by switching between md and html mode for the table header/anchors and the table definitions. This provides the wanted functionality and also uses the Markdown standard for the anchors.

I'll provide a related PR soon. Paul

1. You actually raised a good point about the menu entries which I did not realise. Looking at the structure of the four files, I think that it is ok to have the AO2D categories in ao2dTables as second-level headings appearing in the menu. (I don't think that the heading "AO2D files" is needed.) In helperTaskTables, I think we don't want to have the workflows to appear in the menu, so keeping them as the third-level would be better which would also match the workflow level in pwgTables where the second-level headings are the PWGs. joinsAndIterators is missing the top-level heading, so there I think the current four-level heading "List of defined joins and iterators" just needs to be moved up and promoted to the first level.

2. You're right. There seem to be a few issues with the parsing of anchors in markdown-link-check (see e.g. anchor link checking is broken tcort/markdown-link-check#225). Apparently, it should be able to handle the id= anchors as well but it is not the case at the moment. I think that using <a name= should make markdown-link-check happy but please do not spend too much time on it if it comes with more complications.

Thanks again for looking into that.

[vkucera]

Fixed with AliceO2Group/analysis-framework#211, #10843
Thanks @pbuehler