Scaffolding for C++ docs (#185)

* Initial setup for C++ docs.

* Set up crosslinking of Python and C++ docs.

* Add at least some mainpage for C++ docs.

build_docs.sh

@@ -3,4 +3,7 @@
 # Propagate failures properly
 set -e
 
+# Build C++ docs first so the Python docs can make use of the tag file
+./docs/m.css/documentation/doxygen.py docs/Doxyfile-mcss
+
 ./docs/m.css/documentation/python.py docs/conf.py

docs/Doxyfile-mcss

@@ -0,0 +1,40 @@
+@INCLUDE = Doxyfile
+
+## Patches for the m.css-generated docs. Just need to generate XML, that's it.
+
+GENERATE_HTML          = NO
+GENERATE_XML           = YES
+XML_PROGRAMLISTING     = NO
+
+# TODO: remove
+##! M_SHOW_UNDOCUMENTED    = YES
+##! M_MAIN_PROJECT_URL = https://aihabitat.org/
+
+##! M_CLASS_TREE_EXPAND_LEVELS = 2
+
+##! M_LINKS_NAVBAR1 = \
+##!  "pages" \
+##!  "annotated" \
+##!  "files"
+##! M_LINKS_NAVBAR2 = \
+##!  "<a href="../habitat-sim/index.html">Python docs</a>" \
+##!  "<a href="https://aihabitat.org/habitat-api/">Python API</a>"
+
+ALIASES                = \
+    "cb{1}=@code{\1}" \
+    "cpp=@code{.cpp}" \
+    "glsl=@code{.glsl}" \
+    "cmake=@code{.cmake}" \
+    "ce=@endcode" \
+    "m_div{1}=@xmlonly<mcss:div xmlns:mcss=\"http://mcss.mosra.cz/doxygen/\" mcss:class=\"\1\">@endxmlonly" \
+    "m_enddiv=@xmlonly</mcss:div>@endxmlonly" \
+    "m_span{1}=@xmlonly<mcss:span xmlns:mcss=\"http://mcss.mosra.cz/doxygen/\" mcss:class=\"\1\">@endxmlonly" \
+    "m_endspan=@xmlonly</mcss:span>@endxmlonly" \
+    "m_class{1}=@xmlonly<mcss:class xmlns:mcss=\"http://mcss.mosra.cz/doxygen/\" mcss:class=\"\1\" />@endxmlonly" \
+    "m_footernavigation=@xmlonly<mcss:footernavigation xmlns:mcss=\"http://mcss.mosra.cz/doxygen/\" />@endxmlonly" \
+    "m_examplenavigation{2}=@xmlonly<mcss:examplenavigation xmlns:mcss=\"http://mcss.mosra.cz/doxygen/\" mcss:page=\"\1\" mcss:prefix=\"\2\" />@endxmlonly" \
+    "m_keywords{1}=@xmlonly<mcss:search xmlns:mcss=\"http://mcss.mosra.cz/doxygen/\" mcss:keywords=\"\1\" />@endxmlonly" \
+    "m_keyword{3}=@xmlonly<mcss:search xmlns:mcss=\"http://mcss.mosra.cz/doxygen/\" mcss:keyword=\"\1\" mcss:title=\"\2\" mcss:suffix-length=\"\3\" />@endxmlonly" \
+    "m_enum_values_as_keywords=@xmlonly<mcss:search xmlns:mcss=\"http://mcss.mosra.cz/doxygen/\" mcss:enum-values-as-keywords=\"true\" />@endxmlonly" \
+
+# kate: hl Doxyfile

docs/conf.py

@@ -21,7 +21,7 @@
 PROJECT_SUBTITLE = "Sim Python docs"
 MAIN_PROJECT_URL = "https://aihabitat.org"
 INPUT_MODULES = [habitat_sim]
-INPUT_DOCS = ["docs.rst"]
+INPUT_DOCS = ["docs.rst", "gfx.rst"]
 INPUT_PAGES = [
     "pages/index.rst",
     "pages/new-actions.rst",
@@ -110,3 +110,28 @@
         _hex_colors_dst, code
     )
 }
+
+M_DOX_TAGFILES = [
+    # TODO: the path should be relative to this file
+    (
+        os.path.join(os.path.realpath(os.path.dirname(__file__)), "corrade.tag"),
+        "https://doc.magnum.graphics/corrade/",
+        ["Corrade::"],
+        ["m-doc-external"],
+    ),
+    (
+        os.path.join(os.path.realpath(os.path.dirname(__file__)), "magnum.tag"),
+        "https://doc.magnum.graphics/magnum/",
+        ["Magnum::"],
+        ["m-doc-external"],
+    ),
+    (
+        os.path.join(
+            os.path.realpath(os.path.dirname(__file__)),
+            "../build/docs/habitat-cpp/habitat-cpp.tag",
+        ),
+        "../habitat-cpp/",
+        [],
+        ["m-doc-external"],
+    ),
+]