Skip to content

Commit 7b2ce84

Browse files
coder137coder137
authored
Sphinx documentation (#174)
1 parent aa8a0ee commit 7b2ce84

13 files changed

+270
-10
lines changed

‎.github/workflows/pages.yml

+47
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
name: github pages
2+
3+
on:
4+
push:
5+
branches:
6+
- main # Set a branch name to trigger deployment
7+
8+
env:
9+
# Customize the CMake build type here (Release, Debug, RelWithDebInfo, etc.)
10+
BUILD_TYPE: Release
11+
12+
jobs:
13+
deploy:
14+
runs-on: ubuntu-20.04
15+
steps:
16+
- uses: actions/checkout@v2
17+
with:
18+
submodules: true
19+
20+
- name: Setup
21+
run: |
22+
sudo apt-get install ninja-build doxygen graphviz python3-sphinx
23+
pip install breathe sphinx_rtd_theme furo
24+
25+
- name: Configure CMake
26+
shell: bash
27+
working-directory: ${{github.workspace}}
28+
run: |
29+
cmake -B build -G Ninja -DCMAKE_BUILD_TYPE=$BUILD_TYPE -DBUILDCC_DOCUMENTATION=ON
30+
31+
- name: Build
32+
working-directory: ${{github.workspace}}
33+
shell: bash
34+
run: cmake --build build --config $BUILD_TYPE
35+
36+
- name: Doxygen + Sphinx
37+
working-directory: ${{github.workspace}}/build
38+
shell: bash
39+
run: |
40+
cmake --build . --target doxygen_documentation
41+
cmake --build . --target sphinx_documentation
42+
43+
- name: Deploy
44+
uses: peaceiris/actions-gh-pages@v3
45+
with:
46+
github_token: ${{ secrets.GITHUB_TOKEN }}
47+
publish_dir: ./docs/output

‎.gitignore

+1
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@ _deps
1717
.vs/
1818
.idea/
1919
.cache/
20+
docs/output
2021

2122
# Files
2223
*.gcov

‎CMakePresets.json

+3-3
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,7 @@
2727
"BUILDCC_TESTING": true,
2828
"BUILDCC_CLANGTIDY": true,
2929
"BUILDCC_CPPCHECK": true,
30-
"BUILDCC_DOCUMENTATION": true,
30+
"BUILDCC_DOCUMENTATION": false,
3131
"BUILDCC_NO_DEPRECATED": false
3232
}
3333
},
@@ -52,7 +52,7 @@
5252
"BUILDCC_TESTING": true,
5353
"BUILDCC_CLANGTIDY": true,
5454
"BUILDCC_CPPCHECK": true,
55-
"BUILDCC_DOCUMENTATION": true,
55+
"BUILDCC_DOCUMENTATION": false,
5656
"BUILDCC_NO_DEPRECATED": false
5757
}
5858
},
@@ -77,7 +77,7 @@
7777
"BUILDCC_TESTING": true,
7878
"BUILDCC_CLANGTIDY": true,
7979
"BUILDCC_CPPCHECK": true,
80-
"BUILDCC_DOCUMENTATION": true,
80+
"BUILDCC_DOCUMENTATION": false,
8181
"BUILDCC_NO_DEPRECATED": false
8282
}
8383
},

‎cmake/tool/doxygen.cmake

+12-7
Original file line numberDiff line numberDiff line change
@@ -9,16 +9,21 @@ if (${BUILDCC_DOCUMENTATION})
99
*test/*
1010
*mock/*
1111
)
12-
set(DOXYGEN_BUILTIN_STL_SUPPORT YES)
1312
set(DOXYGEN_EXTRACT_ALL YES)
14-
set(DOXYGEN_MARKDOWN_SUPPORT YES)
15-
set(DOXYGEN_WARN_IF_UNDOCUMENTED NO)
16-
set(DOXYGEN_USE_MDFILE_AS_MAINPAGE ${CMAKE_CURRENT_SOURCE_DIR}/README.md)
13+
set(DOXYGEN_WARN_IF_UNDOCUMENTED YES)
14+
set(DOXYGEN_GENERATE_XML YES)
1715
doxygen_add_docs(doxygen_documentation
18-
${CMAKE_CURRENT_SOURCE_DIR}/README.md
19-
${CMAKE_CURRENT_SOURCE_DIR}/TODO.md
20-
${CMAKE_CURRENT_SOURCE_DIR}/example/README.md
2116
${CMAKE_CURRENT_SOURCE_DIR}/buildcc
2217
COMMENT "Doxygen documentation"
2318
)
19+
20+
find_program(sphinx_build
21+
NAMES "sphinx-build"
22+
REQUIRED
23+
)
24+
add_custom_target(sphinx_documentation
25+
COMMAND ${sphinx_build} -b html -Dbreathe_projects.buildcc_documentation=${CMAKE_CURRENT_BINARY_DIR}/xml . ../output
26+
WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/docs/source
27+
VERBATIM USES_TERMINAL
28+
)
2429
endif()

‎docs/source/arch/design_patterns.rst

+2
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
Design Patterns
2+
===============

‎docs/source/arch/namespaces.rst

+2
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
Namespaces
2+
==========

‎docs/source/arch/outputs.rst

+2
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
Outputs
2+
=======

‎docs/source/arch/project_layout.rst

+2
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
Project Layout
2+
==============

‎docs/source/arch/software_heirarchy.rst

+2
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
Software Heirarchy
2+
==================

‎docs/source/arch/testing.rst

+2
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
Testing
2+
=======

‎docs/source/conf.py

+59
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
# Configuration file for the Sphinx documentation builder.
2+
#
3+
# This file only contains a selection of the most common options. For a full
4+
# list see the documentation:
5+
# https://www.sphinx-doc.org/en/master/usage/configuration.html
6+
7+
# -- Path setup --------------------------------------------------------------
8+
9+
# If extensions (or modules to document with autodoc) are in another directory,
10+
# add these directories to sys.path here. If the directory is relative to the
11+
# documentation root, use os.path.abspath to make it absolute, like shown here.
12+
#
13+
# import os
14+
# import sys
15+
# sys.path.insert(0, os.path.abspath('.'))
16+
17+
18+
# -- Project information -----------------------------------------------------
19+
20+
project = 'BuildCC'
21+
copyright = '2021, Niket Naidu'
22+
author = 'Niket Naidu'
23+
24+
# The full version, including alpha/beta/rc tags
25+
release = '0.1.1'
26+
27+
28+
# -- General configuration ---------------------------------------------------
29+
30+
# Add any Sphinx extension module names here, as strings. They can be
31+
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
32+
# ones.
33+
extensions = [
34+
"breathe"
35+
]
36+
37+
breathe_default_project = "buildcc_documentation"
38+
breathe_default_members = ("members", "undoc-members")
39+
40+
# Add any paths that contain templates here, relative to this directory.
41+
templates_path = ['_templates']
42+
43+
# List of patterns, relative to source directory, that match files and
44+
# directories to ignore when looking for source files.
45+
# This pattern also affects html_static_path and html_extra_path.
46+
exclude_patterns = []
47+
48+
49+
# -- Options for HTML output -------------------------------------------------
50+
51+
# The theme to use for HTML and HTML Help pages. See the documentation for
52+
# a list of builtin themes.
53+
#
54+
html_theme = 'furo'
55+
56+
# Add any paths that contain custom static files (such as style sheets) here,
57+
# relative to this directory. They are copied after the builtin static files,
58+
# so a file named "default.css" will overwrite the builtin "default.css".
59+
html_static_path = ['_static']

‎docs/source/index.rst

+30
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
.. BuildCC documentation master file, created by
2+
sphinx-quickstart on Sun Dec 19 02:26:23 2021.
3+
You can adapt this file completely to your liking, but it should at least
4+
contain the root `toctree` directive.
5+
6+
Welcome to BuildCC's documentation!
7+
===================================
8+
9+
.. toctree::
10+
:maxdepth: 2
11+
:caption: Contents
12+
13+
page/user_api
14+
15+
.. toctree::
16+
:caption: Architecture
17+
18+
arch/project_layout
19+
arch/software_heirarchy
20+
arch/namespaces
21+
arch/design_patterns
22+
arch/testing
23+
arch/outputs
24+
25+
Indices and tables
26+
==================
27+
28+
* :ref:`genindex`
29+
* :ref:`modindex`
30+
* :ref:`search`

‎docs/source/page/user_api.rst

+106
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
*********
2+
User API
3+
*********
4+
5+
Environment
6+
===========
7+
8+
env.h
9+
-----
10+
11+
.. doxygenfunction:: is_init
12+
13+
.. doxygenfunction:: get_project_root_dir
14+
15+
.. doxygenfunction:: get_project_build_dir
16+
17+
logging.h
18+
---------
19+
20+
.. doxygenfunction:: log_trace
21+
22+
.. doxygenfunction:: log_debug
23+
24+
.. doxygenfunction:: log_info
25+
26+
.. doxygenfunction:: log_warning
27+
28+
.. doxygenfunction:: log_critical
29+
30+
assert_fatal.h
31+
--------------
32+
33+
assert_throw.h
34+
--------------
35+
36+
command.h
37+
---------
38+
39+
Toolchain
40+
=========
41+
42+
toolchain.h
43+
------------
44+
45+
toolchain_verify.h
46+
------------------
47+
48+
Generator
49+
=========
50+
51+
generator.h
52+
-----------
53+
54+
TargetInfo
55+
==========
56+
57+
target_info.h
58+
--------------
59+
60+
Target
61+
=======
62+
63+
target.h
64+
---------
65+
66+
Toolchain specialized
67+
=====================
68+
69+
toolchain_gcc.h
70+
----------------
71+
72+
toolchain_msvc.h
73+
-----------------
74+
75+
Target specialized
76+
==================
77+
78+
target_custom.h
79+
---------------
80+
81+
target_gcc.h
82+
-------------
83+
84+
target_msvc.h
85+
-------------
86+
87+
target_generic.h
88+
-----------------
89+
90+
Args
91+
====
92+
93+
args.h
94+
-------
95+
96+
Register
97+
========
98+
99+
register.h
100+
-----------
101+
102+
First Party Plugins
103+
===================
104+
105+
clang_compile_commands.h
106+
------------------------

0 commit comments

Comments
 (0)