You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Using Sphinx to generate the final documentation would be really nice. This is what LLVM, and HPX do nowadays. I've followed https://devblogs.microsoft.com/cppblog/clear-functional-c-documentation-with-sphinx-breathe-doxygen-cmake/ and am able to build and import Doxygen XML output, and render the result in Sphinx. However, there are some issues I've found with the way Sphinx handles template parameters. I've made minimal examples and filed bug reports upstream, sphinx-doc/sphinx#7367 and sphinx-doc/sphinx#7368. Once those are resolved we should be able to use Sphinx to wrap Doxygen documentation. The long-term goal would be to support both Doxygen HTML and Sphinx HTML, but I'm not yet sure that'll be possible. There are a few things I've noticed:
I get: /docs/index.rst: WARNING: Could not lex literal_block as "cpp". Highlighting skipped. but don't know what this is about.
I'm not sure if we can share Markdown tutorials between Doxygen and Sphinx. It would be nice if we can since then we can support full documentation in both Sphinx and Doxygen.
Using exhale did not work. Everything blew up horribly and it's fairly easy to replicate the part of the functionality that we would need, e.g. having a script that parses GroupDefs and generates an rst file that lists all the groups in alphabetical order.
We will want to document the python bindings. I'm not sure if that can be done through Doxygen, but that would probably be the "best" way to handle it if we want to support both full Doxygen and Sphinx documentation.
We will want to auto-generate all the Group documentation and
namespace documentation. For Doxygen groups this should be easy since
we can just simply parse GroupDefs.hpp and generate an RST file from
that. The namespaces will be more difficult, but one option would be
to read and parse Doxygen's XML using Beautifulsoup4 or lxml. There is
a package, Exhale, that should generate both of these for us but I got
errors about "multiple references for..." that as far as I can tell are
related to overloads (and maybe template specializations). Regardless,
at least the groups will be easy to parse, and if parsing namespaces
from XML isn't too bad we can also parse the groups that way. We could
even write a Sphinx extension for ourselves. My only worry with the
Sphinx extension is that I don't know how much maintenance that'll
require to keep working as Sphinx changes, while a simple python script
that generates RST files would fairly be easy to maintain independent
of what Sphinx does.
Component:
Code
Documentation
Build system
Continuous integration
The text was updated successfully, but these errors were encountered:
Feature request:
Using Sphinx to generate the final documentation would be really nice. This is what LLVM, and HPX do nowadays. I've followed https://devblogs.microsoft.com/cppblog/clear-functional-c-documentation-with-sphinx-breathe-doxygen-cmake/ and am able to build and import Doxygen XML output, and render the result in Sphinx. However, there are some issues I've found with the way Sphinx handles template parameters. I've made minimal examples and filed bug reports upstream, sphinx-doc/sphinx#7367 and sphinx-doc/sphinx#7368. Once those are resolved we should be able to use Sphinx to wrap Doxygen documentation. The long-term goal would be to support both Doxygen HTML and Sphinx HTML, but I'm not yet sure that'll be possible. There are a few things I've noticed:
Duplicate target detected:
, e.g./docs/index.rst: WARNING: Could not lex literal_block as "cpp". Highlighting skipped.
but don't know what this is about.GroupDefs
and generates anrst
file that lists all the groups in alphabetical order.namespace documentation. For Doxygen groups this should be easy since
we can just simply parse
GroupDefs.hpp
and generate an RST file fromthat. The namespaces will be more difficult, but one option would be
to read and parse Doxygen's XML using Beautifulsoup4 or lxml. There is
a package, Exhale, that should generate both of these for us but I got
errors about "multiple references for..." that as far as I can tell are
related to overloads (and maybe template specializations). Regardless,
at least the groups will be easy to parse, and if parsing namespaces
from XML isn't too bad we can also parse the groups that way. We could
even write a Sphinx extension for ourselves. My only worry with the
Sphinx extension is that I don't know how much maintenance that'll
require to keep working as Sphinx changes, while a simple python script
that generates RST files would fairly be easy to maintain independent
of what Sphinx does.
Component:
The text was updated successfully, but these errors were encountered: