readthedocs: Add doxygen-generated docs for sdk, and placeholder to a…

…dd more sdk docs (#902)
open-telemetry · Jul 13, 2021 · 6681cd4 · 6681cd4
1 parent be32bde
commit 6681cd4
Show file tree

Hide file tree

Showing 15 changed files with 86 additions and 155 deletions.
diff --git a/api/docs/Makefile b/api/docs/Makefile
diff --git a/api/docs/conf.py b/api/docs/conf.py
diff --git a/api/docs/index.rst b/api/docs/index.rst
diff --git a/api/docs/Doxyfile → docs/public/Doxyfile b/api/docs/Doxyfile → docs/public/Doxyfile
@@ -790,15 +790,20 @@ WARN_LOGFILE           =
 # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
 # Note: If this tag is empty the current directory is searched.
 
-INPUT                  = ../include/opentelemetry/baggage \
-                         ../include/opentelemetry/context \
-                         ../include/opentelemetry/common \
-                         ../include/opentelemetry/nostd/shared_ptr.h \
-                         ../include/opentelemetry/nostd/span.h \
-                         ../include/opentelemetry/nostd/string_view.h \
-                         ../include/opentelemetry/nostd/unique_ptr.h \
-                         ../include/opentelemetry/nostd/variant.h \
-                         ../include/opentelemetry/trace
+INPUT                  =  \
+                         ../../api/include/opentelemetry/baggage \
+                         ../../api/include/opentelemetry/context \
+                         ../../api/include/opentelemetry/common \
+                         ../../api/include/opentelemetry/nostd/shared_ptr.h \
+                         ../../api/include/opentelemetry/nostd/span.h \
+                         ../../api//include/opentelemetry/nostd/string_view.h \
+                         ../../api/include/opentelemetry/nostd/unique_ptr.h \
+                         ../../api/include/opentelemetry/nostd/variant.h \
+                         ../../api/include/opentelemetry/trace \
+                          ../../sdk/include/opentelemetry/sdk/instrumentationlibrary \
+                          ../../sdk/include/opentelemetry/sdk/resource \
+                          ../../sdk/include/opentelemetry/sdk/trace
+
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses
@@ -838,12 +843,12 @@ RECURSIVE              = YES
 # Note that relative paths are relative to the directory from which doxygen is
 # run.
 
-EXCLUDE                = ../include/opentelemetry/common/spin_lock_mutex.h \
-                         ../include/opentelemetry/common/key_value_iterable_view.h \
-                         ../include/opentelemetry/common/kv_properties.h \
-                         ../include/opentelemetry/common/string_util.h \
-                         ../include/opentelemetry/trace/span_context_kv_iterable_view.h \
-                         ../include/opentelemetry/nostd
+EXCLUDE                = ../../api/include/opentelemetry/common/spin_lock_mutex.h \
+                         ../../api/include/opentelemetry/common/key_value_iterable_view.h \
+                         ../../api/include/opentelemetry/common/kv_properties.h \
+                         ../../api/include/opentelemetry/common/string_util.h \
+                         ../../api/include/opentelemetry/trace/span_context_kv_iterable_view.h \
+                         ../../api/include/opentelemetry/nostd
 
 # The EXCLUDE_SYMLINKS tag can be used to select whether or not files or
 # directories that are symbolic links (a Unix file system feature) are excluded

diff --git a/docs/public/Makefile b/docs/public/Makefile
@@ -21,5 +21,4 @@ help:
 
 clean:
 	rm -rf doxyoutput
-	@$(SPHINXBUILD) -M clean ../../api/docs "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 	@$(SPHINXBUILD) -M clean "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/docs/public/GettingStarted.rst → docs/public/api/GettingStarted.rst b/docs/public/GettingStarted.rst → docs/public/api/GettingStarted.rst
diff --git a/docs/public/Overview.rst → docs/public/api/Overview.rst b/docs/public/Overview.rst → docs/public/api/Overview.rst
diff --git a/docs/public/api/api.rst b/docs/public/api/api.rst
@@ -0,0 +1,8 @@
+Opentelmetry C++ API
+====================
+
+.. toctree::
+   :maxdepth: 1
+
+   Overview.rst
+   GettingStarted.rst
diff --git a/docs/public/conf.py b/docs/public/conf.py
@@ -30,28 +30,8 @@
 import os
 import shutil
 import subprocess
-
-apidir = os.path.join('..', '..', 'api', 'docs')
-subprocess.call(['make', 'html'], cwd=apidir)
-targetdir = os.path.join(os.getcwd(), 'otel_api')
-sourcedir = os.path.join(apidir, 'otel_api')
-if os.path.exists(targetdir):
-  shutil.rmtree(targetdir)
-os.makedirs(targetdir)
-
-# Now copying the previously created APi documentation. Table of contents
-# are filtered out, because those don't go well together with the furo theme.
-for fname in os.listdir(sourcedir):
-  with open(os.path.join(sourcedir, fname), 'r') as fin:
-    with open(os.path.join(targetdir, fname), 'w') as fout:
-      skip = False
-      for line in fin:
-        if line.startswith('.. contents'):
-          skip = True
-        elif not line.startswith(' '):
-          skip = False
-        if not skip:
-          fout.write(line)
+if not os.path.exists('doxyoutput'):
+        os.makedirs('doxyoutput')
 
 # -- General configuration ---------------------------------------------------
 
@@ -60,13 +40,24 @@
 # ones.
 extensions = [
     "breathe",
+    "exhale"
 ]
 
+exhale_args = {
+        "containmentFolder": "otel_docs",
+        "rootFileName": "otel_docs.rst",
+        "rootFileTitle": "Reference documentation",
+        "doxygenStripFromPath": "..",
+        "exhaleExecutesDoxygen": True,
+        "exhaleUseDoxyfile": True,
+        "createTreeView": True
+}
+
 breathe_projects = {
-        "OpenTelemetry C++ API": "../../api/docs/doxyoutput/xml"
+        "OpenTelemetry C++": "doxyoutput/xml",
 }
+breathe_default_project = "OpenTelemetry C++"
 
-breathe_default_project = "OpenTelemetry C++ API"
 
 primary_domain = "cpp"
 
@@ -87,7 +78,8 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = "furo"
+#html_theme = "furo"
+html_theme = "sphinx_rtd_theme"
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,

diff --git a/docs/public/index.rst b/docs/public/index.rst
@@ -5,9 +5,36 @@ OpenTelemetry C++
    :maxdepth: 1
    :caption: OpenTelemetry C++ API
 
-   Overview.rst
-   GettingStarted.rst
-   otel_api/otel_api
+   api/api
+
+.. toctree::
+   :maxdepth: 1
+   :caption: OpenTelemetry C++ SDK
+
+   sdk/sdk
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Reference Documentation
+
+   otel_docs/otel_docs
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Reference Documentation (API)
+
+   otel_docs/namespace_opentelemetry__trace
+   otel_docs/namespace_opentelemetry__baggage
+   otel_docs/namespace_opentelemetry__common
+   otel_docs/namespace_opentelemetry__context
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Reference Documentation (SDK)
+
+   otel_docs/namespace_opentelemetry__sdk__trace
+   otel_docs/namespace_opentelemetry__sdk__instrumentationlibrary
+   otel_docs/namespace_opentelemetry__sdk__resource
 
 .. toctree::
    :maxdepth: 1

diff --git a/api/docs/resources/footer.html → docs/public/resources/footer.html b/api/docs/resources/footer.html → docs/public/resources/footer.html
diff --git a/api/docs/resources/header.html → docs/public/resources/header.html b/api/docs/resources/header.html → docs/public/resources/header.html
diff --git a/api/docs/resources/stylesheet.css → docs/public/resources/stylesheet.css b/api/docs/resources/stylesheet.css → docs/public/resources/stylesheet.css
diff --git a/docs/public/sdk/GettingStarted.rst b/docs/public/sdk/GettingStarted.rst
@@ -0,0 +1,4 @@
+Getting started
+---------------
+
+TBD
diff --git a/docs/public/sdk/sdk.rst b/docs/public/sdk/sdk.rst
@@ -0,0 +1,7 @@
+OpenTelemetry C++ SDK
+====================
+
+.. toctree::
+   :maxdepth: 1
+
+   GettingStarted.rst