From 10a66c89dc3f5c9a2655dcd3550d8766f5a84ba6 Mon Sep 17 00:00:00 2001 From: Vamsi Date: Wed, 27 Nov 2024 00:40:42 +0100 Subject: [PATCH] added button to go back to docs --- ...rmat-lint-ci.yml => build_format_lint.yml} | 0 ...h_pages.yml => mkdocs_gh_pages_deploy.yml} | 19 +++- CMakeLists.txt | 5 +- Doxyfile.in | 8 +- README.md | 104 +++++++++--------- docs/styles/doxy.css | 30 ++++- docs/styles/doxy_header.html | 96 ++++++++++++++++ 7 files changed, 198 insertions(+), 64 deletions(-) rename .github/workflows/{build-format-lint-ci.yml => build_format_lint.yml} (100%) rename .github/workflows/{mkdocs_ci_gh_pages.yml => mkdocs_gh_pages_deploy.yml} (66%) create mode 100644 docs/styles/doxy_header.html diff --git a/.github/workflows/build-format-lint-ci.yml b/.github/workflows/build_format_lint.yml similarity index 100% rename from .github/workflows/build-format-lint-ci.yml rename to .github/workflows/build_format_lint.yml diff --git a/.github/workflows/mkdocs_ci_gh_pages.yml b/.github/workflows/mkdocs_gh_pages_deploy.yml similarity index 66% rename from .github/workflows/mkdocs_ci_gh_pages.yml rename to .github/workflows/mkdocs_gh_pages_deploy.yml index 6b3414c..6808206 100644 --- a/.github/workflows/mkdocs_ci_gh_pages.yml +++ b/.github/workflows/mkdocs_gh_pages_deploy.yml @@ -32,7 +32,22 @@ jobs: - name: Install dependencies run: | sudo apt-get update - sudo apt-get install -y doxygen cmake + sudo apt-get install -y cmake graphviz flex bison + + - name: Install Doxygen from source + run: | + wget https://doxygen.nl/files/doxygen-1.12.0.src.tar.gz + tar -xvzf doxygen-1.12.0.src.tar.gz + cd doxygen-1.12.0 + mkdir build + cd build + cmake -G "Unix Makefiles" .. + make -j $(nproc) + sudo make install + cd ../.. + # Clean up + rm -rf doxygen-1.12.0 + rm doxygen-1.12.0.src.tar.gz - name: Build API docs run: | @@ -42,7 +57,7 @@ jobs: cmake --build . --target docs - mv docs/html ../docs/api_html + mv docs/api_html ../docs/api_html - uses: actions/cache@v4 with: diff --git a/CMakeLists.txt b/CMakeLists.txt index c173c30..d15f3c9 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -34,15 +34,14 @@ if(ENABLE_DOC) set(DOXYGEN_INCLUDE_DIR "${CMAKE_SOURCE_DIR}/include") # Path to include directory set(DOXYGEN_README "${CMAKE_SOURCE_DIR}/README.md") # Path to README.md set(DOXYGEN_OUTPUT_DIR "${CMAKE_BINARY_DIR}/docs") # Output directory for the docs - # set(HTML_EXTRA_STYLESHEET "${CMAKE_SOURCE_DIR}/docs/styles/doxy.css") # Path to custom CSS - # file + set(HTML_EXTRA_STYLESHEET "${CMAKE_SOURCE_DIR}/docs/styles/doxy.css") # Path to custom CSS + set(HTML_HEADER "${CMAKE_SOURCE_DIR}/docs/styles/doxy_header.html") # Path to custom header # Ensure that the output directory exists file(MAKE_DIRECTORY ${DOXYGEN_OUTPUT_DIR}) # Provide path to Doxygen config file set(DOXYGEN_CONFIG_FILE "${CMAKE_SOURCE_DIR}/Doxyfile.in") # Path to your Doxygen configuration - # file # Check if Doxygen configuration file exists if(EXISTS "${DOXYGEN_CONFIG_FILE}") diff --git a/Doxyfile.in b/Doxyfile.in index 7fca655..ca9bd2a 100644 --- a/Doxyfile.in +++ b/Doxyfile.in @@ -340,7 +340,7 @@ MARKDOWN_SUPPORT = YES # Minimum value: 0, maximum value: 99, default value: 5. # This tag requires that the tag MARKDOWN_SUPPORT is set to YES. -TOC_INCLUDE_HEADINGS = 0 +TOC_INCLUDE_HEADINGS = 5 # When enabled doxygen tries to link words that correspond to documented # classes, or namespaces to their corresponding documentation. Such a link can @@ -1192,7 +1192,7 @@ GENERATE_HTML = YES # The default directory is: html. # This tag requires that the tag GENERATE_HTML is set to YES. -HTML_OUTPUT = html +HTML_OUTPUT = api_html # The HTML_FILE_EXTENSION tag can be used to specify the file extension for each # generated HTML page (for example: .htm, .php, .asp). @@ -1219,7 +1219,7 @@ HTML_FILE_EXTENSION = .html # of the possible markers and block names see the documentation. # This tag requires that the tag GENERATE_HTML is set to YES. -HTML_HEADER = +HTML_HEADER = @HTML_HEADER@ # The HTML_FOOTER tag can be used to specify a user-defined HTML footer for each # generated HTML page. If the tag is left blank doxygen will generate a standard @@ -1254,7 +1254,7 @@ HTML_STYLESHEET = # list). For an example see the documentation. # This tag requires that the tag GENERATE_HTML is set to YES. -HTML_EXTRA_STYLESHEET = /home/batsy/c_cpp_pkg_template/docs/styles/doxy.css +HTML_EXTRA_STYLESHEET = @HTML_EXTRA_STYLESHEET@ # The HTML_EXTRA_FILES tag can be used to specify one or more extra images or # other source files which should be copied to the HTML output directory. Note diff --git a/README.md b/README.md index d2967ab..ac605cc 100644 --- a/README.md +++ b/README.md @@ -2,44 +2,6 @@ This repository is a template for C/C++ packages. -## Package structure - -``` bash -. -└── c_cpp_pkg_template - ├── .clang-format - ├── .clang-tidy - ├── CMakeLists.txt - ├── docs - │ ├── assets - │ │ └── placeholder - │ ├── index.md - │ └── javascripts - │ └── mathjax.js - ├── .github - │ └── workflows - │ └── mkdocs_ci_gh_pages.yml - ├── .gitignore - ├── include - │ └── PackageName - │ ├── temp.hpp - │ └── template.h - ├── mkdocs.yaml - ├── PackageName-config.cmake.in - ├── .pre-commit-config.yaml - ├── README.md - ├── src - │ ├── CMakeLists.txt - │ ├── example - │ │ ├── CMakeLists.txt - │ │ └── temp_ex.c - │ └── template.c - └── test - ├── CMakeLists.txt - ├── main_test.c - └── temp_test.c -``` - ## Setup ### Prerequisites @@ -47,21 +9,22 @@ This repository is a template for C/C++ packages. - CMake - C/C++ compiler - check (unit testing framework) +- Doxygen - clang-format - clang-tidy -- pre-commit +- [pre-commit](https://pre-commit.com/) #### Install prerequisites -``` bash -sudo apt-get install check clang-format clang-tidy +```bash +sudo apt-get install doxygen check clang-format clang-tidy pip install pre-commit ``` ### Workspace setup -``` bash +```bash mkdir ~/c_cpp_ws && cd ~/c_cpp_ws mkdir build install src @@ -77,7 +40,7 @@ You can use any directory structure you prefer. 1. Clone the repository - ``` bash + ```bash cd ~/c_cpp_ws/src git clone git@github.com:secorolab/c_cpp_pkg_template.git @@ -85,7 +48,7 @@ You can use any directory structure you prefer. 2. Rename the cloned repository - ``` bash + ```bash mv c_cpp_pkg_template cd @@ -104,7 +67,7 @@ or 2. Add the necessary content to the files 3. Initialize the git repository - ``` bash + ```bash git init ``` @@ -116,7 +79,7 @@ or 2. Run the following command in the `root` directory of the package to install the pre-commit hooks. - ``` bash + ```bash pre-commit install ``` @@ -124,7 +87,7 @@ or 1. Create a build directory for the package - ``` bash + ```bash cd ~/c_cpp_ws/build mkdir PackageName && cd PackageName @@ -132,19 +95,22 @@ or 2. Run the following command in the build directory - ``` bash - cmake -DCMAKE_INSTALL_PREFIX=../../install ../../src/PackageName -DCMAKE_BUILD_TYPE=Debug \ - -DCMAKE_EXPORT_COMPILE_COMMANDS=ON -DENABLE_TESTS=ON + ```bash + cmake -DCMAKE_INSTALL_PREFIX=../../install ../../src/PackageName \ + -DCMAKE_BUILD_TYPE=Debug \ + -DCMAKE_EXPORT_COMPILE_COMMANDS=ON \ + -DENABLE_TESTS=ON ``` - `-DCMAKE_INSTALL_PREFIX=../../install`: Specifies the installation directory - `-DCMAKE_BUILD_TYPE=Debug`: Specifies the build type (Debug, Release, RelWithDebInfo, MinSizeRel) - `-DCMAKE_EXPORT_COMPILE_COMMANDS=ON`: Generates compile_commands.json file - `-DENABLE_TESTS=ON`: Enables the unit tests + - `-DENABLE_DOC=ON`: Enables the documentation generation 3. Build the package - ``` bash + ```bash make -j $(nproc) ``` @@ -152,10 +118,40 @@ or 4. Install the package - ``` bash + ```bash make install ``` +## Configs + +### MkDocs + +- To generate the documentation, you can use the [MkDocs](https://www.mkdocs.org/) tool. +- The [mkdocs.yaml](mkdocs.yaml) file contains the configuration for the documentation. +- Refer to the Plugins and Reference sections in the [Material for MkDocs documentation](https://squidfunk.github.io/mkdocs-material/reference/) +for more information about the configuration. + +### Doxygen + +- To generate the documentation, you can use the [Doxygen](https://www.doxygen.nl/index.html) tool. +- The [Doxyfile](Doxyfile.in) file contains the default configuration for the documentation. + > [!IMPORTANT] -> Refer the [best practices](https://github.com/secorolab/.github-private/blob/main/best_practices/c_cpp.md) -for more information. +> Configure the [mkdocs.yaml](mkdocs.yaml) and [mkdocs_gh_pages_deploy.yml](/github/workflows/mkdocs_gh_pages_deploy.yml) +files accordingly based on whether your project has API documentation or not. + +### Pre-commit + +- The [pre-commit-config.yaml](.pre-commit-config.yaml) file contains the configuration for the +pre-commit hooks. +- Update the `build` and `install` paths in the `clang-format` and `clang-tidy` hooks, based on your +workspace setup. +- Also, update the `Set up build` and `Configure and build` in the [build_format_lint.yml](.github/workflows/build_format_lint.yml), +if you have a different build setup. + +### GitHub Actions + +- The [build_format_lint.yml](.github/workflows/build_format_lint.yml) file contains the configuration +to test the package build, and check the code formatting and linting. +- The [mkdocs_gh_pages_deploy.yml](.github/workflows/mkdocs_gh_pages_deploy.yml) file contains the +configuration to deploy the documentation to GitHub Pages. diff --git a/docs/styles/doxy.css b/docs/styles/doxy.css index 5502b41..9cb9d47 100644 --- a/docs/styles/doxy.css +++ b/docs/styles/doxy.css @@ -102,4 +102,32 @@ #nav-path ul li a img{ width: 5em; -} \ No newline at end of file +} + +.nav-button-goto-docs-atag { + display: inline-block; + background-color: transparent; + border: 2px solid white; + color: white; + padding: 1px 5px; + font-size: 12px; + text-align: center; + text-decoration: none; + cursor: pointer; + transition: all 0.3s ease; + margin-left: 1em; + margin-bottom: 0.5em; + border-radius: 5px; + } + + .nav-button-goto-docs-atag:hover { + background-color: var(--md-accent-fg-color); + text-decoration: none; + color: black; + border-color: white; + } + + #side-nav { + min-width: 275px; + max-width: 50vw; + } \ No newline at end of file diff --git a/docs/styles/doxy_header.html b/docs/styles/doxy_header.html new file mode 100644 index 0000000..4a05f91 --- /dev/null +++ b/docs/styles/doxy_header.html @@ -0,0 +1,96 @@ + + + + + + + + + + + $projectname: $title + + $title + + + + + + + + + + + + + + + $treeview + $search + $mathjax + $darkmode + + $extrastylesheet + + + + + +
+ + + +
+ + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
$projectname $projectnumber +
+ +
$projectbrief
+ 		+
$projectbrief
+ 		$searchbox
$searchbox + + Docs + +
+
+ + + \ No newline at end of file