Tweak the code blocks

[javiereguiluz]

This updates the generated HTML for code listings or code blocks. I've been studying the way code blocks are highlighted in the best modern websites (GitHub, Stripe, etc.) and I think we should do the same. The final HTML is much less verbose, it doesn't rely on tables and the new HTML features are universally supported in browsers.

I'll update tests after rebasing when the other PR related to code is merged. Thanks!

[nikophil]

nice simplification 👍
I've merged the previous PR ;)

[javiereguiluz]

I've rebased and fixed the tests ... but some needed changes in fixtures look wrong 😐

[nikophil]

Hi @javiereguiluz

are you talking about glob toc tree order? (the remaining failing test).
TBH I don't know why we had at some point this problem, but it may come from a recent change from the parser. Look at the same file in master branch, the order is the same than in your test. I think we can safely merge that.

[javiereguiluz]

@nikophil I don't understand well your comment, but:

• In my local machine all tests pass ... I don't see the failure that I'm seeing here.
• Even if tests pass, it's really strange that expected fixtures need so many changes, specially the unrelated changes. E.g. in this file -> https://github.com/weaverryan/docs-builder/pull/69/files#diff-4e6e575a71cad6392b960e4661a258a091eba3b031ee57e8b45fdc0fc30cfdbf why has the <header> changed at all? This looks suspicious to me.

[javiereguiluz]

If I can do something to make this mergeable, please tell me. Thanks!

[nikophil]

hi @javiereguiluz

sorry not to be clear.

about the failing test in the PR

On my side, I DO have the errors on my local machine (php 7.4 / up to date with dependencies)

In the PR, one test is failing. It is related to both of these toc trees:

.. toctree::
    :glob:

    *

.. toctree::
    :glob:

    file
    *

Thus the problem in the tests is definitely related to the glob option: the "top level" file index.html is linked before the "deeper level" file directory/another_file.html, but we're expecting the other way in tests/fixtures/expected/toctree/index.html.

Under the hood, "glob search" is based on symfony/finder, I don't know how it is possible that we have different outputs, but I think the behavior we want is "top level first" (basically, the behavior we got in the CI). Moreover you can see, that in master branch, we're making the right expectation.

For the second problem

Maybe I've not understood the situation, but I don't think we have a problem: the content of the html has not changed, the only thing that has changed is indentation. It totally depends on how you've made the expected html file.
You can have a look to these lines: https://github.com/weaverryan/docs-builder/blob/master/tests/IntegrationTest.php#L67-L72
we're not comparing directly file contents, but we compare it after some "indentation processing", thus we shouldn't take really care about the html indentation in our fixtures.

[javiereguiluz]

Nicolas, thanks for your detailed explanation. I've fixed the tests as you suggested and I'm leaving "as is" the changed HTML content of the other tests. Cheers!

[nikophil]

But now, tests are failing on your (local) side?

[javiereguiluz]

Yes 🙈

But CI server and your own local tests work ... so maybe we can ignore my own issues.

[nikophil]

😞

I can see you're on a mac, I'm on ubuntu (as well as the CI)... May not glob search a bit depending on the environment?
This could be a real problem, the toc items would be in different order depending on which environment the doc was generated... ?

/cc @weaverryan WDYT ?

[javiereguiluz]

If possible, we'd need this change merged soon ... maybe we can merge this and tackle the TOC glob problem in another issue --> #72. Thanks!