added button to go back to docs

.github/workflows/mkdocs_ci_gh_pages.yml → .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:

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}")

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

README.md

@@ -2,66 +2,29 @@
 
 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
 
 - 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,15 +40,15 @@ You can use any directory structure you prefer.
 
 1. Clone the repository
 
-    ``` bash
+    ```bash
     cd ~/c_cpp_ws/src
 
     git clone [email protected]:secorolab/c_cpp_pkg_template.git
     ```
 
 2. Rename the cloned repository
 
-    ``` bash
+    ```bash
     mv c_cpp_pkg_template <PackageName>
 
     cd <PackageName>
@@ -104,7 +67,7 @@ or
 2. Add the necessary content to the files
 3. Initialize the git repository
 
-    ``` bash
+    ```bash
     git init
     ```
 
@@ -116,46 +79,79 @@ or
 
 2. Run the following command in the `root` directory of the package to install the pre-commit hooks.
 
-    ``` bash
+    ```bash
     pre-commit install
     ```
 
 ## Build and install
 
 1. Create a build directory for the package
 
-    ``` bash
+    ```bash
     cd ~/c_cpp_ws/build
 
     mkdir PackageName && cd PackageName
     ```
 
 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)
     ```
 
     - If `ENABLE_TESTS` is set to `ON`, the tests will be built as well.
 
 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.

docs/styles/doxy.css

@@ -102,4 +102,32 @@
 
 #nav-path ul li a img{
     width: 5em;
-}
+}
+
+.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;
+  }