Add documentation generation through Breathe / Sphinx

[TheLartians]

The current generated Doxygen docs work great, however the generated site doesn't have a particularly modern style and the customisation options are limited. Afaik we can use Doxygen together with Breathe / Sphinx to get much better looking docs. If it doesn't require too much boilerplate code I'd love to include that here.

[chaitan94]

One other interesting option is to use m.css, I did a little experimentation integrating it with this template on my fork. Here is how the output looks: http://moderncppstarter-mcss-docs.surge.sh/index.html

Compared to default doxygen template, I say it looks much more modern - and just.. better. Best part, IMO, is the quick search feature as soon as you press tab. It increases usability by a lot. Also it is mobile friendly.

I know this is not Breathe/Sphinx but I thought I'd share it here in case anyone finds it useful/interesting.

[TheLartians]

Hey, thanks for showing me m.css, that does look much better and especially it seems to work on mobile too! I think we could definitely use this as a lightweight alternative to Breathe / Sphinx for the starter. If you want, you can open a PR from your branch and we can work on adding it to the starter.

One thing I've noticed is that the Pages and Files tabs both appear empty in your fork. Is that a configuration issue?

[chaitan94]

One thing I've noticed is that the Pages and Files tabs both appear empty in your fork. Is that a configuration issue?

Yes about that, I noticed it too. Apparently, this is a feature from m.css side. So by default in m.css, unlike doxygen, anything undocumented would not be populated in the final output, so as to encourage good documentation practices. In the case of ModernCppStarter we do not have explicit documentation for any page or file using @page or @file so they are not included. (Although there seems to be a way to disable this behavior).

So, for full context, I did try to add them manually, but I couldn't get the output working even after adding the documentation for them. I did not spend much time on it later. And to be honest, this is the first time I am using m.css too, so I may be missing something here. If you want I can open a PR of what we have upto this point.

[TheLartians]

Hm I do see the point in encouraging explicit good practices, though imo there is nothing wrong in an auto-generated pages and files glossary (I even think it's a good idea as it reduces redundancy and potential mistakes). Maybe we can figure out how to enable them again.

I think creating a PR with the current progress is a good start and we work on the issues from there.