Use m.css for generating doxygen docs

[chaitan94]

Here is the output: http://moderncppstarter-mcss-docs.surge.sh/index.html

Addresses https://github.com/TheLartians/ModernCppStarter/issues/47 (although a bit indirectly).

Also, note that right now, these are pending:

• [x] The Pages and Files tabs have empty content, as m.css does not include undocumented entities by default in the output. We need to fix this by adding related documentation.
• [x] Previously Doxygen was filled using env variables, ex: @DOXYGEN_PROJECT_ROOT@, but now they have to be hardcoded. Maybe this can be improved.

[codecov[bot]]

Codecov Report

Merging #49 into master will not change coverage. The diff coverage is n/a.

@@            Coverage Diff            @@
##            master       #49   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files            2         2           
  Lines           12        12           
=========================================
  Hits            12        12           

Impacted Files	Coverage Δ
include/greeter/greeter.h	100.00% <ø> (ø)

---

Continue to review full report at Codecov.

Legend - Click here to learn more Δ = absolute <relative> (impact), ø = not affected, ? = missing data Powered by Codecov. Last update 2f1b5fa...6665c5d. Read the comment docs.

[chaitan94]

@TheLartians I made the change to pass CMake variables to Doxygen.

Additionally, I also got the Pages section working. Plus I also added sample code to get started with configuring the navbar more easily.

Before:

After:

However, the Files section is still empty. I am still not sure why. If you have time, could you try it out? If not, maybe I'll revisit this later sometime.

[TheLartians]

Super, thanks for the quick updates! I'll take a look into the files section as soon as I have some time as well.

[TheLartians]

So apparently the option M_SHOW_UNDOCUMENTED allows us to disable the feature that hides undocumented objects (including directories, files and namespaces), which allows us to create the files page without explicitly documenting directories. This also allows us to document classes again without needing to explicitly document outer namespaces. The disadvantage is that all files now appear in the "Files" section, even those without any documentation relevance. However, I prefer this setting, as it makes it easier for users to start and add documentation to their projects which they can refine later on.

However to do so, I needed to fix a small bug in m.css that caused a crash when the option was enabled. Therefore we are currently using my fork of m.css to build the docs. I've opened a PR with the fix there that I hope it will be resolved soon.

[chaitan94]

Nice updates. It feels much better now. 🔥

The disadvantage is that all files now appear in the "Files" section, event those without any documentation relevance.

Perhaps, is there a way we can include files based on extension? Say only .c, .h, .cpp, .cc and .hpp?

[TheLartians]

Glad to hear that! :)

Not sure if it's possible to filter by file type and depending on the project it might even be desirable to document certain files that aren't relevant for us. It would be nice if there was an option to simply hide files that contain no documentation info and cannot be parsed by Doxygen. IMO though the current solution of showing more than necessary is good enough for the starter and users that are serious about docs can eventually disable M_SHOW_UNDOCUMENTED.

[chaitan94]

Yeah, I also agree that enabling M_SHOW_UNDOCUMENTED is a fair choice for a starter template.

I think we can go ahead with using your fork of m.css. It seems the PRs in the original repo are not merged so frequently, so that might take a while.

[TheLartians]

Good point, I'll make a quick change to the comment and will go ahead with merging the PR.

[TheLartians]

After updating the dependencies in the CI script the new docs are live and look way better. 🚀 Thank you for the contribution!