diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml new file mode 100644 index 00000000..af5b39a2 --- /dev/null +++ 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 index 92ed69eb..3394fcf1 100644 --- a/.gitignore +++ b/.gitignore @@ -17,6 +17,7 @@ _deps .vs/ .idea/ .cache/ +docs/output # Files *.gcov diff --git a/CMakePresets.json b/CMakePresets.json index 55023307..68fb595c 100644 --- 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 index 82401577..ead0bb12 100644 --- 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 new file mode 100644 index 00000000..d8c48a46 --- /dev/null +++ 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 new file mode 100644 index 00000000..76d5098a --- /dev/null +++ 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 new file mode 100644 index 00000000..4286020c --- /dev/null +++ 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 new file mode 100644 index 00000000..9e0223cf --- /dev/null +++ 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 new file mode 100644 index 00000000..c527510a --- /dev/null +++ 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 new file mode 100644 index 00000000..96994bb8 --- /dev/null +++ b/docs/source/arch/testing.rst @@ -0,0 +1,2 @@ +Testing +======= diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 00000000..cc559fbc --- /dev/null +++ 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 new file mode 100644 index 00000000..2df0d915 --- /dev/null +++ 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 new file mode 100644 index 00000000..590e1e52 --- /dev/null +++ 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 +------------------------