Merge pull request #3 from Synchrotron-Radiation-Workshop/cpp_docs

C++ Docs to Sphinx via Doxygen and Breathe

docs/Doxyfile_core

@@ -0,0 +1,13 @@
+PROJECT_NAME     = "SRW Core"
+OUTPUT_DIRECTORY = build
+XML_OUTPUT       = doxyxml_core
+GENERATE_LATEX   = NO
+GENERATE_MAN     = NO
+GENERATE_RTF     = NO
+CASE_SENSE_NAMES = NO
+INPUT            = ../src/core
+RECURSIVE        = YES
+QUIET            = YES
+JAVADOC_AUTOBRIEF = YES
+GENERATE_HTML = NO
+GENERATE_XML = YES

docs/Doxyfile_lib

@@ -0,0 +1,13 @@
+PROJECT_NAME     = "SRW Lib"
+OUTPUT_DIRECTORY = build
+XML_OUTPUT       = doxyxml_lib
+GENERATE_LATEX   = NO
+GENERATE_MAN     = NO
+GENERATE_RTF     = NO
+CASE_SENSE_NAMES = NO
+INPUT            = ../src/lib
+RECURSIVE        = YES
+QUIET            = YES
+JAVADOC_AUTOBRIEF = YES
+GENERATE_HTML = NO
+GENERATE_XML = YES

docs/Makefile

@@ -2,7 +2,7 @@
 #
 
 # You can set these variables from the command line.
-SPHINXOPTS    = "-W"  # This flag turns warnings into errors.
+SPHINXOPTS    = #"-W"  # This flag turns warnings into errors.
 SPHINXBUILD   = sphinx-build
 SPHINXPROJ    = srwpy
 SOURCEDIR     = source
@@ -17,4 +17,6 @@ help:
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
+	@doxygen Doxyfile_core
+	@doxygen Doxyfile_lib
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/source/api/cpp/core.rst

@@ -0,0 +1,5 @@
+SRW Core
+========
+
+.. doxygenindex::
+    :project: SRWCore

docs/source/api/cpp/index.rst

@@ -0,0 +1,8 @@
+SRW C++
+=======
+
+.. toctree::
+    :maxdepth: 1
+
+    core
+    lib

docs/source/api/cpp/lib.rst

@@ -0,0 +1,5 @@
+SRW Lib
+=======
+
+.. doxygenindex::
+    :project: SRWLib

docs/source/api/index.rst

@@ -2,8 +2,13 @@ API
 ===
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
    :caption: Python
 
    python/_modules/modules.rst
 
+.. toctree::
+   :maxdepth: 1
+   :caption: C++
+
+   cpp/index.rst

docs/source/api/python/_modules/modules.rst

@@ -1,5 +1,5 @@
-srwpy
-=====
+SRW Python
+==========
 
 .. toctree::
    :maxdepth: 4

docs/source/conf.py

@@ -17,6 +17,7 @@
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 
+import breathe
 import os
 import sys
 import re
@@ -36,7 +37,7 @@
 # ones.
 extensions = [
     'sphinx.ext.autodoc',
-    'sphinx.ext.autosummary',
+    # 'sphinx.ext.autosummary',
     'sphinx.ext.githubpages',
     'sphinx.ext.intersphinx',
     'sphinx.ext.mathjax',
@@ -47,6 +48,7 @@
     'numpydoc',
     'sphinx_copybutton',
     'sphinx_gallery.gen_gallery',
+    'breathe'
 ]
 
 autodoc_mock_imports = ["pykern", "skimage"]
@@ -208,8 +210,6 @@
 ]
 
 
-
-
 # Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {
     'python': ('https://docs.python.org/3/', None),
@@ -218,3 +218,12 @@
     'pandas': ('https://pandas.pydata.org/pandas-docs/stable', None),
     'matplotlib': ('https://matplotlib.org', None),
 }
+
+# -- Options for Breathe output --------------------------------
+
+# Breath configuration
+breathe_projects = {
+    'SRWCore': '../build/doxyxml_core',
+    'SRWLib': '../build/doxyxml_lib'
+}
+breathe_default_project = 'SRWCore'

python/requirements-dev.txt

@@ -13,6 +13,8 @@ pillow # required by sphinx-gallery
 sphinx-copybutton
 sphinx-gallery
 sphinx_rtd_theme
+doxygen
+breathe
 # PyPI deployment tools
 setuptools
 twine