documentation viewer

[LecrisUT]

Description
Currently there are 2 open PRs suggesting documentation builders:

• Add mkdocs #2672
• [Add Feature] View docs in a more comfortable way #2478
• docs: Sphinx + ReadTheDocs  #2710

I believe that is a valuable feature, but I believe it's missing RTD suppott that would make the documentations:

• searchable
• version specific
• viewable on PRs

For this I think it's valuable to implement an established standard of sphinx. What are your opinions?

[adehad]

Sphinx with the readthedocs github integration (so it runs on each PR etc) would be a great option.

Happy to support this effort, I have got it working with markdown files before

[nrbnlulu]

IMO mkdocs-material looks much better then Sphinx although Sphinx is considered more mature, AFAIK recent projects
tends to use mkdocs over sphinx.

searchable - ✔️

version specific

Doable on mkdocs

viewable on PRs

This is not specific to mkdocs or Sphinx, You'll need to setup a PaaS for that, I don't think github
support this out of the box.

[LecrisUT]

Both mkdocs and sphinx are supported for rtd out-of-the-box, so I am inclined to either.

On the specifics of mkdocs vs sphinx, I want to check:

• Are there equivalents to myst-parser supported functions, specifically:
  • Admotions like caution, warning, note, etc.
  • Tab-set
  • Include from-to functionality, either as code or as markdown to be processed
• Is there a set of themes to see them in action like at sphinx-themes.org
• Is there support for doxygen like in breathe? E.g. including contents of a whole doxygen group?
• Does mkdocs have an autobuild/live editor where when you change the md source or doxygen comments it rebuilds of itself so you have a live web view of it?
• Are there any other specific features to mkdocs that might not be on sphinx?
• This one is a bonus, is there an equivalent to inter-sphinx, where you can link to items in other projects and you get a pop-up with a preview of that content?

[nrbnlulu]

• Are there equivalents to myst-parser supported functions, specifically:

  • Admotions like caution, warning, note, etc. - ✔️
  • Tab-set - ✔️
  • Include from-to functionality, either as code or as markdown to be processed - ✔️

• Is there a set of themes to see them in action like at sphinx-themes.org - ❌
  Everyone just use mkdocs-material because it looks awesome, well maintained, and feature rich.

• Is there support for doxygen like in breathe? E.g. including contents of a whole doxygen group?

• Does mkdocs have an autobuild/live editor where when you change the md source or doxygen comments it rebuilds of itself so you have a live web view of it?

No, (not that sphinx does) we'll need to craft something on our own using the xml doxygen generates...

• Are there any other specific features to mkdocs that might not be on sphinx?

I don't think so.

• This one is a bonus, is there an equivalent to inter-sphinx, where you can link to items in other projects and you get a pop-up with a preview of that content?

Not that I know.

---

Note that the majority of features that Sphinx provide over mkdocs are Python specific.
I only use mkdocs to generate html from markdown and it does it much better then Sphinx IMO.

[LecrisUT]

Not having breathe is a major bummer for a cpp project. There are quite a few api documentations that should br exposed and synchronized between the docs file and in-code.

It is helpful to have this discussion before we get locked-in by designing for a specific ecosystem. If the only criteria is the looks, then check the sphinx-theme.org and comment on what is missing there. I like RTD and furo theme. Other contenders are book, pydata and materials (lesser because of how api view is generated out-of-the-box).

Both ecosystems are constantly growing so who knows how they will evolve.

[nrbnlulu]

Not having breathe is a major bummer for a cpp project. There are quite a few api documentations that should br exposed and synchronized between the docs file and in-code.

Typical Catch2 usage is with macros more than with classes so it is not much of a bummer + it doesn't look very good and we can craft something ourselfs using doxygen xml.

If the only criteria is the looks, then check the sphinx-theme.org and comment on what is missing there. I like RTD and furo theme. Other contenders are book, pydata and materials (lesser because of how api view is generated out-of-the-box).

• mkdocs-material is incomparable to these themes and is much more mature.

• It is not the only one, mkdocs is much easier to understand, maintain, extend and it is build for markdown while sphinx is
  first-class rst, although it has markdown integrations.

[LecrisUT]

Typical Catch2 usage is with macros more than with classes so it is not much of a bummer + it doesn't look very good

Note that macros are supported by doxygen and breathe. Source and generated.

Also with C++ modules, it is unclear how macros will continue to exist as exported API. It will be great if the api behind the macros are also documented.

sphinx is first-class rst, although it has markdown integrations.

myst-parser is plenty mature at this point, and various projects rely on it.

[nrbnlulu]

Yeah, anyways, thanks for your input! I would continue my mkdocs PR tonight 🤞 and leave for maintainers
to decide what would be best...

[nrbnlulu]

FWIW here is mkdocs C++ generated API https://json.nlohmann.me/api/basic_json/

[hwhsu1231]

Any progress of this issue? Personally, I prefer the Sphinx one, since the layout is more beautiful to me.

Screenshot from @LecrisUT 's example: https://catch2-temp.readthedocs.io/en/latest/