alandefreitas / matplotplusplus

Matplot++: A C++ Graphics Library for Data Visualization 📊🗾
https://alandefreitas.github.io/matplotplusplus/
MIT License
4.34k stars 334 forks source link

Remove block indent from code and images to fix GitHub view #275

Closed NeroBurner closed 2 years ago

NeroBurner commented 2 years ago

In the GitHub rendering of README.md the lines starting with four spaces are converted to a verbatim block. Instead of showing the picture we now see the markdown instead. The same happens to the indented cpp code blocks.

To fix the GitHub rendering remove those blocks.

alandefreitas commented 2 years ago

Hi @NeroBurner ! Thanks for looking at this.

This would be nice, but the problem is this would break the documentation website. The documentation is generated from the README.md file: the sections are split into pages, mkdocs takes it from there, Github actions builds it and uploads it to the documentation branch, and GitHub pages publishes it.

So this indentation has a specific meaning on Github pages. For instance,

=== "Ubuntu + GCC"

    ```bash
    g++ --version

is telling mkdocs + github pages this should be a [content tab](https://squidfunk.github.io/mkdocs-material/reference/content-tabs/).

Likewise, 

```markdown
=== "Windows + MSVC"

    !!! warning ""
        * Visit the [Visual Studio](https://visualstudio.microsoft.com) website
        * Download Git from [https://git-scm.com/download/win](https://git-scm.com/download/win) and install it

is telling mkdocs + github pages this should be an admonition inside another content tab.

To be fair, not everything is rendered properly sometimes because the .github workflow needs to be updated from time to time. Nonetheless, that's what it's supposed to do and 99% of it works.

However, I have indeed noticed this as a problem. In all of my recent projects, I tend to include just a big link to documentation in the README.md file, then concentrate all the documentation on the website, where it's beautiful to read. It simplified the workflow considerably and there's no point in incentivizing people to do the wrong thing anyway. The initial plan was to have both look reasonable but, as more formatting is required for the website, there's no benefit in reading from a source that's not rendered yet.

This is quite easy to achieve. I just haven't done it for matplot++ yet because I'm drowning in work. I have lots of nice plans for matplot++ when I have some spare time.

If you want to have a look at that, the process is not that complicated: it's just a matter of running mdsplit on README.md locally, moving these files to docs, updating the workflow to ignore the mdsplit step, and updating README.md with a big link to the documentation. There are a few templates for that:

One really nice thing in FetchBoostContent is the macros allow us to replicate some partial content from README.md in docs/index.md, which is really useful. It's also simpler to copy/paste the template because it's smaller.

What's nice about the "futures" template is that it includes the reference, which is easy to cherry-pick from the template. FetchBoostContent doesn't include that because it's related to C++/CMake but not a C++ library.