Doxygen ALIASES for extensions

[jpgarza93]

Hello, as always thank you for your awesome work, dedication, and time.

Here is something we started doing lately to simplify docs writing. Instead of using HTML directly in markdown (which markdownlints are not a fan of and looks messy), we started creating ALIASES with the HTML. For example:

Tabs

Instead of adding this to the markdown:

<div class="tabbed">
 
- <b class="tab-title">Tab 1</b> This is the content of tab 1
- <b class="tab-title">Tab 2</b> This is the content of tab 2
 
</div>

We add this to the markdown:

@tabs{ 
  @tab{ Tab 1 | This is the content of tab 1 } 
  @tab{ Tab 2 | This is the content of tab 2 } 
}

with an alias:

# tabs
ALIASES += tab{2|}="@htmlonly<li><b class=\"tab-title\">@endhtmlonly^^\1^^@htmlonly</b>@endhtmlonly^^\2^^@htmlonly</li>@endhtmlonly"
ALIASES += tabs{1}="@htmlonly<div class=\"tabbed\"><ul>@endhtmlonly^^\1^^@htmlonly</ul></div><br>@endhtmlonly"

Other Aliases

# markers
ALIASES += red{1}="<span style=\"color:red\">\1</span>"
ALIASES += blue{1}="<span style=\"color:blue\">\1</span>"
ALIASES += green{1}="<span style=\"color:green\">\1</span>"
ALIASES += yellow{1}="<span style=\"color:yellow\">\1</span>"
# expander
ALIASES += expander{2|}="@htmlonly<details><summary>^^\1^^</summary><div>@endhtmlonly^^\2^^@htmlonly</div></details>@endhtmlonly"

@red{ Red content }
@expander{ Title | Description }

---

I think these can make the experience better when writing docs and we can start adding more extensions if we can provide ALIASES to copy-paste. Just a thought :)

Look at my docs here https://support.roboticsys.com/rmp/camming.html#autotoc_md278 to see them render in HTML.

Let me know what you think!

[jothepro]

Nice! I like it! 😊
My main motivation behind the syntax for tabs and the navigation buttons was to keep it as compatible as possible with GitHub-flavored Markdown. Tabs will mostly render just fine as lists in GitHub, and the navigation buttons will be displayed as a table. Admittedly, the resulting syntax is quite verbose, which is why I like your approach to hide it behind aliases!

[jpgarza93]

Glad to hear you like the approach :)

[ReenigneArcher]

The tab aliases are nice!

Any idea how to make it a little more robust?

@tabs{
   @tab{ General | @code{.bash}sunshine --help@endcode }
   @tab{ AppImage | @code{.bash}./sunshine.AppImage --help@endcode }
   @tab{ Flatpak | @code{.bash}flatpak run --command=sunshine dev.lizardbyte.app.Sunshine --help@endcode }
}

The above works, but the below isn't so nice.

@tabs{
   @tab{ General |
       @code{.bash}
       sunshine --help
       @endcode
   }
   @tab{ AppImage |
       @code{.bash}
       ./sunshine.AppImage --help
       @endcode
   }
   @tab{ Flatpak |
       @code{.bash}
       flatpak run --command=sunshine dev.lizardbyte.app.Sunshine --help
       @endcode
    }
}

P.S. I did something similar to your colored spans as well, you might find interesting. #155

[jpgarza93]

Where does it fail with your 2nd approach?

[ReenigneArcher]

I found it works if I ensure the code block starts after the pipe, instead of on the next line.

e.g. This works.

   @tab{ General | @code{}
       sunshine --help
       @endcode
   }

[jpgarza93]

I tested on my side with the code below and it worked okay. My guess is that your indenting might be messing things up? The parameters passed are being passed as Markdown and not as HTML.

Some text here

@tabs{
@tab{ Tab1 |
@code{}
tab1 sunshine --help
@endcode
}
@tab{ Tab2 |
@code{}
tab2 sunshine --help
@endcode
}
}

Some text here

[ReenigneArcher]

My guess is that your indenting might be messing things up?

That seems logical.

[ReenigneArcher]

There seems to be an issue with these when using Doxygen 1.13.

/home/langer/github.com/sunshine/docs/getting_started.md:485: error: Found unknown command '@ilinebr'
/home/langer/github.com/sunshine/docs/getting_started.md:486: error: Found unknown command '@ilinebr'
/home/langer/github.com/sunshine/docs/getting_started.md:486: error: Found unknown command '@ilinebr'
/home/langer/github.com/sunshine/docs/getting_started.md:486: error: Found unknown command '@ilinebr'
/home/langer/github.com/sunshine/docs/getting_started.md:488: error: Found unknown command '@ilinebr'
/home/langer/github.com/sunshine/docs/getting_started.md:489: error: Found unknown command '@ilinebr'
/home/langer/github.com/sunshine/docs/getting_started.md:489: error: Found unknown command '@ilinebr'
/home/langer/github.com/sunshine/docs/getting_started.md:489: error: Found unknown command '@ilinebr'
/home/langer/github.com/sunshine/docs/getting_started.md:491: error: Found unknown command '@ilinebr'
/home/langer/github.com/sunshine/docs/getting_started.md:492: error: Found unknown command '@ilinebr'
/home/langer/github.com/sunshine/docs/getting_started.md:492: error: Found unknown command '@ilinebr'
/home/langer/github.com/sunshine/docs/getting_started.md:492: error: Found unknown command '@ilinebr'
/home/langer/github.com/sunshine/docs/getting_started.md:494: error: Found unknown command '@ilinebr'
/home/langer/github.com/sunshine/docs/getting_started.md:495: error: Found unknown command '@ilinebr'

https://github.com/LizardByte/Sunshine/blob/5793ff74ebd68f92ec824563b823531ce80c303e/docs/getting_started.md?plain=1#L485-L495

/home/langer/github.com/sunshine/third-party/doxyconfig/docs/source_code.md:141: error: Found unknown command '@ilinebr'
/home/langer/github.com/sunshine/third-party/doxyconfig/docs/source_code.md:141: error: Found unknown command '@ilinebr'
/home/langer/github.com/sunshine/third-party/doxyconfig/docs/source_code.md:142: error: Found unknown command '@ilinebr'

https://github.com/LizardByte/doxyconfig/blob/4c9452482bd01cb36764dc914d4537b278ad4218/docs/source_code.md?plain=1#L141-L142

/home/langer/github.com/sunshine/third-party/doxyconfig/docs/source_code.md:156: error: Found unknown command '@ilinebr'
/home/langer/github.com/sunshine/third-party/doxyconfig/docs/source_code.md:156: error: Found unknown command '@ilinebr'

https://github.com/LizardByte/doxyconfig/blob/4c9452482bd01cb36764dc914d4537b278ad4218/docs/source_code.md?plain=1#L156

[FrogTheFrog]

It seems to be somehow related to this issue doxygen/doxygen#11310

[ReenigneArcher]

Looks like they fixed it. Is it available in 1.13.1 or do we need to wait for 1.13.2?