Added base documentation generated from doxyen and sphinx

CMakeLists.txt

@@ -8,7 +8,12 @@ set(CMAKE_EXPORT_COMPILE_COMMANDS ON)
 set(CMAKE_CXX_FLAGS_DEBUG "-DDEBUG=1")
 set(CMAKE_CXX_FLAGS_RELEASE "-DRELEASE=1")
 
+set(CMAKE_VERBOSE_MAKEFILE on)
+
 option(KOMPUTE_OPT_BUILD_TESTS "Enable if you want to build tests" ON)
+option(KOMPUTE_OPT_BUILD_DOCS "Enable if you want to build documentation" ON)
+
+set(CMAKE_MODULE_PATH "${PROJECT_SOURCE_DIR}/config" ${CMAKE_MODULE_PATH})
 
 # Allow scripts to call main kompute Makefile
 function(kompute_make KOMPUTE_MAKE_TARGET)
@@ -18,6 +23,10 @@ endfunction()
 
 add_subdirectory(src)
 
+if(KOMPUTE_OPT_BUILD_DOCS)
+    add_subdirectory(docs)
+endif()
+
 if(KOMPUTE_OPT_BUILD_TESTS)
     include(CTest)
     enable_testing()

README.md

@@ -36,6 +36,15 @@
 
 ## Getting Started
 
+### Setup
+
+Kompute is provided as a single header file `Kompute.hpp` that can be simply included in your code.
+
+You can go to our [release page]() to grab the latest library or you can [build from source]().
+
+
+### Your first Kompute
+
 Run your tensors against default operations via the Manager.
 
 ```c++
@@ -166,7 +175,17 @@ Simplified Kompute Components
 
 We appreciate PRs and Issues. If you want to contribute try checking the "Good first issue" tag, but even using Vulkan Kompute and reporting issues is a great contribution!
 
-### Dev Overview
+### Contributing
+
+#### Dev Dependencies
+
+* Testing
+    + Catch2
+* Documentation
+    + Doxygen (with Dot)
+    + Sphynx
+
+#### Development
 
 * Follows Mozilla C++ Style Guide https://www-archive.mozilla.org/hacking/mozilla-style-guide.html
     + Uses post-commit hook to run the linter, you can set it up so it runs the linter before commit
@@ -175,4 +194,3 @@ We appreciate PRs and Issues. If you want to contribute try checking the "Good f
 * Uses cmake as build system, and provides a top level makefile with recommended command
 * Uses xxd (or xxd.exe windows 64bit port) to convert shader spirv to header files
 
-

config/FindSphinx.cmake

@@ -0,0 +1,12 @@
+
+#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/CMakeLists.txt

@@ -0,0 +1,57 @@
+
+find_package(Doxygen REQUIRED)
+
+# Parameters to be replaced in Doxifile.in as "@VAR@"
+file(GLOB_RECURSE DOXYGEN_INPUT_FILES_RAW
+    ${PROJECT_SOURCE_DIR}/src/include/kompute/*.hpp)
+# Need to do a string replace as files have to be 
+# space separated and with double quotes
+string(REPLACE ";" "\" \"" 
+    DOXYGEN_INPUT_FILES "${DOXYGEN_INPUT_FILES_RAW}")
+set(DOXYGEN_OUTPUT_DIR 
+    ${CMAKE_CURRENT_BINARY_DIR}/doxygen)
+# DOXIGEN_DOT_PATH is also set automatically
+
+# Parameters only used inside cmake script
+set(DOXYGEN_INDEX_FILE
+    ${DOXYGEN_OUTPUT_DIR}/html/index.html)
+set(DOXYGEN_XML_PATH
+    ${DOXYGEN_OUTPUT_DIR}/xml/)
+set(DOXYFILE_IN
+    ${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in)
+set(DOXYFILE_OUT
+    ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile)
+
+# Perform replacement with cmake vars inside Doxifine.in
+configure_file(${DOXYFILE_IN} ${DOXYFILE_OUT} @ONLY)
+
+file(MAKE_DIRECTORY ${DOXYGEN_OUTPUT_DIR})
+add_custom_command(
+    OUTPUT ${DOXYGEN_INDEX_FILE}
+    COMMAND ${DOXYGEN_EXECUTABLE} ${DOXYFILE_OUT}
+    MAIN_DEPENDENCY ${DOXYFILE_IN} ${DOXYFILE_OUT}
+    COMMENT "Generating docs"
+)
+
+add_custom_target(gendoxygen ALL 
+    DEPENDS ${DOXYGEN_INDEX_FILE})
+
+
+#####################################################
+########### Sphinx ###############
+#####################################################
+
+find_package(Sphinx REQUIRED)
+
+set(SPHINX_SOURCE ${CMAKE_CURRENT_SOURCE_DIR})
+set(SPHINX_BUILD ${CMAKE_CURRENT_BINARY_DIR}/sphinx)
+
+add_custom_target(gensphinx ALL
+    COMMAND
+    ${SPHINX_EXECUTABLE} -b html 
+        ${SPHINX_SOURCE} ${SPHINX_BUILD}
+        -Dbreathe_projects.Kompute=${DOXYGEN_XML_PATH}
+    WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
+    DEPENDS ${DOXYGEN_INDEX_FILE}
+    COMMENT "Generating documentation with Sphinx")
+

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/conf.py

@@ -0,0 +1,76 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# 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 os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+
+# -- Project information -----------------------------------------------------
+
+project = 'Vulkan Kompute'
+copyright = '2020, Alejandro Saucedo'
+author = 'Alejandro Saucedo'
+
+# The full version, including alpha/beta/rc tags
+release = '0.1.0'
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    "breathe"
+]
+
+# Breathe conf
+breathe_default_project = "Kompute"
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+# Chosen Themes:
+# * https://github.com/bashtage/sphinx-material/
+# * https://github.com/myyasuda/sphinx_materialdesign_theme
+html_theme = 'sphinx_material'
+
+if html_theme == 'sphinx_material':
+    html_theme_options = {
+        'nav_title': 'Project Name',
+        #'google_analytics_account': 'UA-XXXXX',
+        #'base_url': 'https://project.github.io/project',
+        'color_primary': 'red',
+        'color_accent': 'light-blue',
+        'repo_url': 'https://github.com/axsaucedo/vulkan-kompute/',
+        'repo_name': 'Vulkan Kompute',
+        'globaltoc_depth': 3,
+        'globaltoc_collapse': False,
+        'globaltoc_includehidden': False,
+    }
+
+# 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,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']

docs/index.rst

@@ -0,0 +1,29 @@
+.. Vulkan Kompute documentation master file, created by
+   sphinx-quickstart on Fri Aug 28 06:42:00 2020.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to Vulkan Kompute's documentation!
+==========================================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+
+Docs
+====
+
+.. doxygenclass:: kp::Manager
+   :members:
+
+.. doxygenclass:: kp::Algorithm
+   :members:
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

scripts/requirements.txt

@@ -1,4 +1,9 @@
-sh==1.13.1
+# CLI dependencies
 click==7.1.2
+
+# Dev dependencies
 black==19.10b0
 quom==1.2.0
+Sphinx==3.2.1
+sphinx_materialdesign_theme==0.1.11
+breathe==4.20.0

single_include/kompute/Kompute.hpp

@@ -233,10 +233,16 @@ class Tensor
 
 namespace kp {
 
+/**
+    Base Operation
+*/
 class OpBase
 {
   private:
   public:
+    /**
+        Constructor
+    */
     OpBase() { SPDLOG_DEBUG("Compute OpBase base constructor"); }
 
     OpBase(std::shared_ptr<vk::PhysicalDevice> physicalDevice,
@@ -250,7 +256,9 @@ class OpBase
         this->mCommandBuffer = commandBuffer;
     }
 
-    ~OpBase() { SPDLOG_DEBUG("Compute OpBase destructor started"); }
+    ~OpBase() {
+        SPDLOG_DEBUG("Compute OpBase destructor started"); 
+    }
 
     virtual void init(std::vector<std::shared_ptr<Tensor>> tensors)
     {
@@ -271,9 +279,15 @@ class OpBase
 
 namespace kp {
 
+/**
+    Container of operations that can be sent to GPU as batch
+*/
 class Sequence
 {
   public:
+    /**
+        Constructor
+    */
     Sequence();
     Sequence(std::shared_ptr<vk::PhysicalDevice> physicalDevice,
              std::shared_ptr<vk::Device> device,
@@ -338,10 +352,16 @@ class Sequence
 
 namespace kp {
 
+/**
+    Base orchestrator which creates and manages device and child components
+*/
 class Manager
 {
   private:
   public:
+    /**
+        Constructor
+    */
     Manager();
 
     Manager(std::shared_ptr<vk::Instance> instance,
@@ -452,10 +472,16 @@ class Algorithm
 
 namespace kp {
 
+/**
+    Base algorithm based operation
+*/
 template<uint32_t tX = 0, uint32_t tY = 0, uint32_t tZ = 0>
 class OpMult : public OpBase
 {
   public:
+    /**
+        Constructor
+    */
     OpMult();
 
     OpMult(std::shared_ptr<vk::PhysicalDevice> physicalDevice,

src/include/kompute/Manager.hpp

@@ -6,10 +6,16 @@
 
 namespace kp {
 
+/**
+    Base orchestrator which creates and manages device and child components
+*/
 class Manager
 {
   private:
   public:
+    /**
+        Constructor
+    */
     Manager();
 
     Manager(std::shared_ptr<vk::Instance> instance,

src/include/kompute/OpBase.hpp

@@ -6,10 +6,16 @@
 
 namespace kp {
 
+/**
+    Base Operation
+*/
 class OpBase
 {
   private:
   public:
+    /**
+        Constructor
+    */
     OpBase() { SPDLOG_DEBUG("Compute OpBase base constructor"); }
 
     OpBase(std::shared_ptr<vk::PhysicalDevice> physicalDevice,
@@ -23,7 +29,9 @@ class OpBase
         this->mCommandBuffer = commandBuffer;
     }
 
-    ~OpBase() { SPDLOG_DEBUG("Compute OpBase destructor started"); }
+    ~OpBase() {
+        SPDLOG_DEBUG("Compute OpBase destructor started"); 
+    }
 
     virtual void init(std::vector<std::shared_ptr<Tensor>> tensors)
     {

src/include/kompute/OpMult.hpp

@@ -13,10 +13,16 @@
 
 namespace kp {
 
+/**
+    Base algorithm based operation
+*/
 template<uint32_t tX = 0, uint32_t tY = 0, uint32_t tZ = 0>
 class OpMult : public OpBase
 {
   public:
+    /**
+        Constructor
+    */
     OpMult();
 
     OpMult(std::shared_ptr<vk::PhysicalDevice> physicalDevice,

src/include/kompute/Sequence.hpp

@@ -6,9 +6,15 @@
 
 namespace kp {
 
+/**
+    Container of operations that can be sent to GPU as batch
+*/
 class Sequence
 {
   public:
+    /**
+        Constructor
+    */
     Sequence();
     Sequence(std::shared_ptr<vk::PhysicalDevice> physicalDevice,
              std::shared_ptr<vk::Device> device,