Sphinx documentation (#174)

coder137 · web-flow · commit 7b2ce84430b2 · 2021-12-19T10:01:24.000-08:00
diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml
@@ -0,0 +1,47 @@
+name: github pages
+
+on:
+  push:
+    branches:
+      - main # Set a branch name to trigger deployment
+
+env:
+  # Customize the CMake build type here (Release, Debug, RelWithDebInfo, etc.)
+  BUILD_TYPE: Release
+
+jobs:
+  deploy:
+    runs-on: ubuntu-20.04
+    steps:
+      - uses: actions/checkout@v2
+        with:
+          submodules: true
+
+      - name: Setup
+        run: |
+          sudo apt-get install ninja-build doxygen graphviz python3-sphinx
+          pip install breathe sphinx_rtd_theme furo
+
+      - name: Configure CMake
+        shell: bash
+        working-directory: ${{github.workspace}}
+        run: |
+          cmake -B build -G Ninja -DCMAKE_BUILD_TYPE=$BUILD_TYPE -DBUILDCC_DOCUMENTATION=ON
+
+      - name: Build
+        working-directory: ${{github.workspace}}
+        shell: bash
+        run: cmake --build build --config $BUILD_TYPE
+
+      - name: Doxygen + Sphinx
+        working-directory: ${{github.workspace}}/build
+        shell: bash
+        run: |
+          cmake --build . --target doxygen_documentation
+          cmake --build . --target sphinx_documentation
+
+      - name: Deploy
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./docs/output
diff --git a/.gitignore b/.gitignore
@@ -17,6 +17,7 @@ _deps
 .vs/
 .idea/
 .cache/
+docs/output
 
 # Files
 *.gcov
diff --git a/CMakePresets.json b/CMakePresets.json
@@ -27,7 +27,7 @@
                 "BUILDCC_TESTING": true,
                 "BUILDCC_CLANGTIDY": true,
                 "BUILDCC_CPPCHECK": true,
-                "BUILDCC_DOCUMENTATION": true,
+                "BUILDCC_DOCUMENTATION": false,
                 "BUILDCC_NO_DEPRECATED": false
             }
         },
@@ -52,7 +52,7 @@
                 "BUILDCC_TESTING": true,
                 "BUILDCC_CLANGTIDY": true,
                 "BUILDCC_CPPCHECK": true,
-                "BUILDCC_DOCUMENTATION": true,
+                "BUILDCC_DOCUMENTATION": false,
                 "BUILDCC_NO_DEPRECATED": false
             }
         },
@@ -77,7 +77,7 @@
                 "BUILDCC_TESTING": true,
                 "BUILDCC_CLANGTIDY": true,
                 "BUILDCC_CPPCHECK": true,
-                "BUILDCC_DOCUMENTATION": true,
+                "BUILDCC_DOCUMENTATION": false,
                 "BUILDCC_NO_DEPRECATED": false
             }
         },
diff --git a/cmake/tool/doxygen.cmake b/cmake/tool/doxygen.cmake
@@ -9,16 +9,21 @@ if (${BUILDCC_DOCUMENTATION})
         *test/*
         *mock/*
     )
-    set(DOXYGEN_BUILTIN_STL_SUPPORT YES)
     set(DOXYGEN_EXTRACT_ALL YES)
-    set(DOXYGEN_MARKDOWN_SUPPORT YES)
-    set(DOXYGEN_WARN_IF_UNDOCUMENTED NO)
-    set(DOXYGEN_USE_MDFILE_AS_MAINPAGE ${CMAKE_CURRENT_SOURCE_DIR}/README.md)
+    set(DOXYGEN_WARN_IF_UNDOCUMENTED YES)
+    set(DOXYGEN_GENERATE_XML YES)
     doxygen_add_docs(doxygen_documentation
-        ${CMAKE_CURRENT_SOURCE_DIR}/README.md
-        ${CMAKE_CURRENT_SOURCE_DIR}/TODO.md
-        ${CMAKE_CURRENT_SOURCE_DIR}/example/README.md
         ${CMAKE_CURRENT_SOURCE_DIR}/buildcc
         COMMENT "Doxygen documentation"
     )
+
+    find_program(sphinx_build
+        NAMES "sphinx-build"
+        REQUIRED
+    )
+    add_custom_target(sphinx_documentation
+    COMMAND ${sphinx_build} -b html -Dbreathe_projects.buildcc_documentation=${CMAKE_CURRENT_BINARY_DIR}/xml . ../output
+    WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/docs/source
+    VERBATIM USES_TERMINAL
+    )
 endif()
diff --git a/docs/source/arch/design_patterns.rst b/docs/source/arch/design_patterns.rst
@@ -0,0 +1,2 @@
+Design Patterns
+===============
diff --git a/docs/source/arch/namespaces.rst b/docs/source/arch/namespaces.rst
@@ -0,0 +1,2 @@
+Namespaces
+==========
diff --git a/docs/source/arch/outputs.rst b/docs/source/arch/outputs.rst
@@ -0,0 +1,2 @@
+Outputs
+=======
diff --git a/docs/source/arch/project_layout.rst b/docs/source/arch/project_layout.rst
@@ -0,0 +1,2 @@
+Project Layout
+==============
diff --git a/docs/source/arch/software_heirarchy.rst b/docs/source/arch/software_heirarchy.rst
@@ -0,0 +1,2 @@
+Software Heirarchy
+==================
diff --git a/docs/source/arch/testing.rst b/docs/source/arch/testing.rst
@@ -0,0 +1,2 @@
+Testing
+=======
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -0,0 +1,59 @@
+# 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 = 'BuildCC'
+copyright = '2021, Niket Naidu'
+author = 'Niket Naidu'
+
+# The full version, including alpha/beta/rc tags
+release = '0.1.1'
+
+
+# -- 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_default_project = "buildcc_documentation"
+breathe_default_members = ("members", "undoc-members")
+
+# 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 = []
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'furo'
+
+# 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']
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -0,0 +1,30 @@
+.. BuildCC documentation master file, created by
+   sphinx-quickstart on Sun Dec 19 02:26:23 2021.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to BuildCC's documentation!
+===================================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents
+
+   page/user_api
+
+.. toctree::
+   :caption: Architecture
+
+   arch/project_layout
+   arch/software_heirarchy
+   arch/namespaces
+   arch/design_patterns
+   arch/testing
+   arch/outputs
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
diff --git a/docs/source/page/user_api.rst b/docs/source/page/user_api.rst
@@ -0,0 +1,106 @@
+*********
+User API
+*********
+
+Environment
+===========
+
+env.h
+-----
+
+.. doxygenfunction:: is_init
+
+.. doxygenfunction:: get_project_root_dir
+
+.. doxygenfunction:: get_project_build_dir
+
+logging.h
+---------
+
+.. doxygenfunction:: log_trace
+
+.. doxygenfunction:: log_debug
+
+.. doxygenfunction:: log_info
+
+.. doxygenfunction:: log_warning
+
+.. doxygenfunction:: log_critical
+
+assert_fatal.h
+--------------
+
+assert_throw.h
+--------------
+
+command.h
+---------
+
+Toolchain
+=========
+
+toolchain.h
+------------
+
+toolchain_verify.h
+------------------
+
+Generator
+=========
+
+generator.h
+-----------
+
+TargetInfo
+==========
+
+target_info.h
+--------------
+
+Target
+=======
+
+target.h
+---------
+
+Toolchain specialized 
+=====================
+
+toolchain_gcc.h
+----------------
+
+toolchain_msvc.h
+-----------------
+
+Target specialized
+==================
+
+target_custom.h
+---------------
+
+target_gcc.h
+-------------
+
+target_msvc.h
+-------------
+
+target_generic.h
+-----------------
+
+Args
+====
+
+args.h
+-------
+
+Register
+========
+
+register.h
+-----------
+
+First Party Plugins
+===================
+
+clang_compile_commands.h
+------------------------

-Original file line number
+Diff line change
 .vs/
 .idea/
 .cache/
 +docs/output
 # Files
 *.gcov
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,2 @@`
	`1`	`+Software Heirarchy`
	`2`	`+==================`