Merge pull request #1297 from IfcOpenShell/docs

Documentation generation by @johltn

.gitignore

@@ -12,6 +12,13 @@ __pycache__
 .vscode
 # PyCharm files
 .idea
+
+# Docs
+/docs/output
+/docs/rst_files
+/docs/doxygen
+/src/ifcblenderexport/docs/_build
+
 # gettext binary translation files
 *.mo
 # Vim

cmake/CMakeLists.txt

@@ -36,6 +36,7 @@ OPTION(IFCXML_SUPPORT "Build IfcParse with ifcXML support (requires libxml2)." O
 OPTION(ENABLE_BUILD_OPTIMIZATIONS "Enable certain compiler and linker optimizations on RelWithDebInfo and Release builds." OFF)
 OPTION(IFCCONVERT_DOUBLE_PRECISION "IfcConvert: Use double precision floating-point numbers." ON)
 OPTION(BUILD_IFCGEOM "Build IfcGeom." ON)
+OPTION(BUILD_DOCUMENTATION "Build IfcOpenShell Documentation." OFF)
 OPTION(BUILD_IFCPYTHON "Build IfcPython." ON)
 OPTION(BUILD_EXAMPLES "Build example applications." ON)
 OPTION(BUILD_GEOMSERVER "Build IfcGeomServer executable." ON)
@@ -655,6 +656,12 @@ INSTALL(TARGETS IfcGeomServer
 
 endif()
 
+# Documentation	
+IF(BUILD_DOCUMENTATION)
+	set(CMAKE_MODULE_PATH "../docs/cmake")
+	ADD_SUBDIRECTORY(../docs docs)
+ENDIF()
+
 IF(BUILD_IFCPYTHON)
 	ADD_SUBDIRECTORY(../src/ifcwrap ifcwrap)
 ENDIF()

docs/CMakeLists.txt

@@ -0,0 +1,40 @@
+#Look for an executable called sphinx-build
+find_program(SPHINX_EXECUTABLE
+             NAMES sphinx-build
+             DOC "Path to sphinx-build executable")
+
+include(FindPackageHandleStandardArgs)
+
+#Handle standard arguments to find_package like REQUIRED and QUIET
+find_package_handle_standard_args(Sphinx
+                                  "Failed to find sphinx-build executable"
+                                  SPHINX_EXECUTABLE)
+
+find_package(Doxygen REQUIRED)
+#find_package(Sphinx REQUIRED)
+
+set(SPHINX_SOURCE ${CMAKE_CURRENT_SOURCE_DIR})
+set(SPHINX_BUILD ${CMAKE_CURRENT_BINARY_DIR}/docs/sphinx)
+
+MESSAGE(STATUS "SPHINX BUILD ${CMAKE_CURRENT_BINARY_DIR}")
+
+file(MAKE_DIRECTORY ./output/doxygen)
+
+if (DOXYGEN_FOUND)
+
+add_custom_target(Sphinx ALL
+                  COMMAND
+                  ${SPHINX_EXECUTABLE} -v -T -b html
+				  ${SPHINX_SOURCE} ${CMAKE_CURRENT_SOURCE_DIR}/output
+				  WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/output
+                  COMMENT "Generating documentation with Sphinx")
+					  
+# add_custom_target(ifcopenshell_python_docs ALL
+                  # COMMAND make html
+                  # WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/../src/ifcblenderexport/docs
+				  # OUTPUT ${CMAKE_CURRENT_SOURCE_DIR}/../src/ifcblenderexport/docs
+                  # COMMENT "Generating documentation with Sphinx")
+	
+else (DOXYGEN_FOUND)
+  message("Doxygen need to be installed to generate the doxygen documentation")
+endif (DOXYGEN_FOUND)

docs/cmake/FindSphinx.cmake

@@ -0,0 +1,11 @@
+#Look for an executable called sphinx-build
+find_program(SPHINX_EXECUTABLE
+             NAMES sphinx-build
+             DOC "Path to sphinx-build executable")
+
+include(FindPackageHandleStandardArgs)
+
+#Handle standard arguments to find_package like REQUIRED and QUIET
+find_package_handle_standard_args(Sphinx
+                                  "Failed to find sphinx-build executable"
+                                  SPHINX_EXECUTABLE)

docs/cmake/SphinxConfig.cmake

@@ -0,0 +1,11 @@
+#Look for an executable called sphinx-build
+find_program(SPHINX_EXECUTABLE
+             NAMES sphinx-build
+             DOC "Path to sphinx-build executable")
+
+include(FindPackageHandleStandardArgs)
+
+#Handle standard arguments to find_package like REQUIRED and QUIET
+find_package_handle_standard_args(Sphinx
+                                  "Failed to find sphinx-build executable"
+                                  SPHINX_EXECUTABLE)

docs/conf.py

@@ -0,0 +1,48 @@
+import textwrap
+# The `extensions` list should already be in here from `sphinx-quickstart`
+extensions = [
+    # there may be others here already, e.g. 'sphinx.ext.mathjax'
+    'breathe',
+    'exhale',
+    'sphinx.ext.intersphinx'
+]
+
+project = 'IfcOpenShell'
+copyright = '2020, IfcOpenShell'
+author = ''
+
+# Setup the breathe extension
+breathe_projects = {
+    "My Project": "./output/doxygen/xml"
+}
+breathe_default_project = "My Project"
+
+# Setup the exhale extension
+exhale_args = {
+    # These arguments are required
+    "containmentFolder":     "./rst_files",
+    "rootFileName":          "library_root.rst",
+    "rootFileTitle":         "IfcOpenShell",
+    "doxygenStripFromPath":  "..",
+    # Suggested optional arguments
+    "createTreeView":        True,
+    # TIP: if using the sphinx-bootstrap-theme, you need
+    # "treeViewIsBootstrap": True,
+    "exhaleExecutesDoxygen": True,
+    # "exhaleDoxygenStdin":    "INPUT = ../src/serializers/ ../src/ifcgeom",
+    "exhaleUseDoxyfile": True
+
+}
+
+
+
+# html_theme = 'sphinx_rtd_theme'
+
+# # Tell sphinx what the primary language being documented is.
+# primary_domain = 'cpp'
+
+# # Tell sphinx what the pygments highlight language should be.
+# highlight_language = 'cpp'
+
+
+

docs/generate_docs.py

@@ -0,0 +1,52 @@
+# This program requires doxygen, sphinx, breathe and exhale.
+
+import os
+import os.path
+import subprocess
+
+from sys import platform
+
+
+def copy_content(content, container):
+	with open(content) as f:
+		with open(container, "w") as f1:
+			for line in f:
+				f1.write(line)
+
+
+conf_path = "./conf.py"
+index_path = "./index.rst"
+
+
+if not os.path.isdir("./output/doxygen/xml"):
+	os.makedirs("output/doxygen/xml")
+
+if os.path.isfile(conf_path) and not os.path.isfile(index_path):
+	os.remove(conf_path) 
+if os.path.isfile(index_path) and not os.path.isfile(conf_path):
+	os.remove(index_path) 
+
+if not (os.path.isfile(conf_path) and os.path.isfile(index_path)):
+	subprocess.run(["sphinx-quickstart", "-q", "-p", "IfcOpenShell"])
+
+conf_copy = ["./conf_to_copy.py", "./conf.py"]
+index_copy = ["./index_to_copy.rst", "./index.rst"]
+
+copy_content(conf_copy[0], conf_copy[1])
+copy_content(index_copy[0], index_copy[1])
+
+if platform == "linux" or platform == "linux2":
+	subprocess.run(["make", "html"])
+	if not os.path.isdir("/output/_build"):
+		subprocess.run(["cd","../src/ifcblenderexport/docs"])
+		subprocess.run(["make", "html"])
+		subprocess.run(["cd", "../../../docs"])
+		
+	subprocess.run(["mv" "../src/ifcblenderexport/docs/_build", "./output"])
+	
+		
+elif platform == "win32" or platform == "win64":
+	subprocess.run(["make.bat", "html"])
+
+
+

docs/index.rst

@@ -0,0 +1,10 @@
+IfcOpenShell
+============
+
+.. toctree::
+   :maxdepth: 3
+
+   rst_files/library_root
+
+
+`ifcopenshell-python documentation <_build/html/index.html>`_

docs/index_to_copy.rst

@@ -0,0 +1,10 @@
+IfcOpenShell
+============
+
+.. toctree::
+   :maxdepth: 3
+
+   rst_files/library_root
+
+
+`ifcopenshell-python documentation <_build/html/index.html>`_