{"id":28717201,"url":"https://github.com/42-course/libftpp","last_synced_at":"2025-08-01T11:36:29.573Z","repository":{"id":294916049,"uuid":"988502203","full_name":"42-Course/libftpp","owner":"42-Course","description":"My first advanced C++ multi-use library","archived":false,"fork":false,"pushed_at":"2025-05-22T16:40:30.000Z","size":232,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-15T03:13:54.889Z","etag":null,"topics":["cplusplus","library"],"latest_commit_sha":null,"homepage":"https://42-course.github.io/libftpp-docs/","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/42-Course.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-05-22T16:32:48.000Z","updated_at":"2025-06-02T09:07:37.000Z","dependencies_parsed_at":"2025-05-22T18:12:56.555Z","dependency_job_id":null,"html_url":"https://github.com/42-Course/libftpp","commit_stats":null,"previous_names":["42-course/libftpp"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/42-Course/libftpp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/42-Course%2Flibftpp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/42-Course%2Flibftpp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/42-Course%2Flibftpp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/42-Course%2Flibftpp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/42-Course","download_url":"https://codeload.github.com/42-Course/libftpp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/42-Course%2Flibftpp/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":268215611,"owners_count":24214365,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-01T02:00:08.611Z","response_time":67,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cplusplus","library"],"created_at":"2025-06-15T03:13:42.040Z","updated_at":"2025-08-01T11:36:29.525Z","avatar_url":"https://github.com/42-Course.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# **libftpp - A C++ Library Project**\n\n`libftpp` is a custom C++ library with extensive automated documentation generation. This project is set up with a `Makefile` that compiles the library, manages object and binary cleanup, and automates documentation generation using Doxygen and Sphinx, with Read the Docs support.\n\n#### View the documentation here: [https://42-course.github.io/libftpp-docs/](https://42-course.github.io/libftpp-docs/)\n\n***\n\n\n## Table of Contents\n- [Project Overview](#project-overview)\n- [Installation](#installation)\n- [Compilation and Testing](#compilation-and-testing)\n  - [Makefile Targets](#makefile-targets)\n- [Documentation Generation](#documentation-generation)\n  - [Doxygen + Sphinx Setup](#doxygen--sphinx-setup)\n    - [Doxygen](#doxygen)\n    - [Sphinx with Breathe](#sphinx-with-breathe)\n  - [Revised Documentation Guidelines](#revised-documentation-guidelines)\n    - [Coding Guidelines](#coding-guidelines)\n    - [Documentation Structure](#documentation-structure)\n      - [File-Level Documentation](#file-level-documentation)\n      - [Class-Level Documentation](#class-level-documentation)\n      - [Method-Level Documentation](#method-level-documentation)\n  - [Makefile Integration](#makefile-integration)\n- [Cleaning Up](#cleaning-up)\n- [Notes](#notes)\n\n---\n\n## Project Overview\n\nThis project, `libftpp`, is designed with an emphasis on:\n- Clean code practices with C++17 standards.\n- Automated documentation generated from source code comments.\n- Consistent build and test workflow.\n\n## Installation\n\nTo set up the environment, you will need to have the following dependencies installed:\n- **Doxygen**: for generating XML documentation from source code.\n- **Sphinx**: for building documentation in various formats.\n- **Read the Docs (RTD)**: to enable a web-hosted documentation view using Sphinx.\n- **myst**: Modern markup support for sphinx\n\nInstall Doxygen and Sphinx via your package manager or using `pip` for Sphinx:\n\n```bash\n# Doxygen installation\n# On Ubuntu\nsudo apt update\nsudo apt install doxygen\n\n# On macOS\nbrew install doxygen\n\n# Sphinx installation\npip install sphinx\npip install sphinx-rtd-theme  # Recommended for Read the Docs theme\n```\n\nInstall the Python dependencies\n\nNext, install all the Python dependencies listed in the `requirements.txt`:\n\n```bash\npip install -r requirements.txt\n```\n\nThis will install:\n\n- **Sphinx**: The tool used for generating the project's documentation.\n- **myst-parser**: Allows Sphinx to parse and render Markdown files.\n\n\n## Compilation and Testing\n\nThis project includes a Makefile with multiple targets for compiling, testing, and cleaning the project.\n\n### Makefile Targets\n\n| Target       | Description |\n|--------------|-------------|\n| `make` (same as make all)   | Compiles the library and generates the `libftpp` executable. |\n| `make all`   | Compiles the library and generates the `libftpp` executable. |\n| `make test`  | Rebuilds the project, runs the compiled binary, and displays test output. |\n| `make valgrind` | Runs the executable with `valgrind` for memory leak checking. |\n| `make clean` | Cleans up all object files and documentation files. |\n| `make fclean`| Performs `clean` and removes the compiled binary and XML files. |\n| `make re`    | Cleans and recompiles the project from scratch. |\n| `make help`  | Displays available Sphinx documentation commands. |\n| `make \u003cdoc\u003e` | Executes a Sphinx documentation build based on the specified output type (e.g., `make html`, `make latex`). |\n\n---\n\n## Documentation Generation\n\n### Doxygen + Sphinx Setup\n\nThis project is set up to generate documentation in two stages:\n1. **Doxygen**: Parses C++ source code comments, outputs XML data.\n2. **Sphinx with Breathe**: Converts Doxygen's XML output into various documentation formats (HTML, PDF, etc.) using Sphinx.\n\n#### Doxygen\n\nThe `Doxyfile` is configured to:\n- Parse only `.cpp`, `.hpp`, and `.inc` files.\n- Generate XML output in the `xml` folder, used by Sphinx/Breathe.\n- Allow Markdown and render it correctly for Sphinx, although there are som \\*bugs\n- Disable `html` and `latex` outputs, to avoid unnecessary folders.\n\n\u003e \\* I founded that sometimes it will not parse Markdown correctly, specially higher level titles `#### For Example`\n\n#### Sphinx with Breathe\n\nSphinx is configured to read the XML output from Doxygen. The following important settings in `conf.py` allow Sphinx to render API documentation:\n- **Extensions**: Includes `breathe`, `sphinx.ext.autodoc`, and `sphinx_rtd_theme`.\n- **Breathe Configuration**: Specifies the project name and XML directory for Breathe to locate Doxygen files.\n\n### Revised Documentation Guidelines\n\nHere are the comprehensive **coding and documentation guidelines** you requested, including your specific points:\n\n---\n\n### Coding Guidelines\n\n1. **Indentation**:\n   - Use **2 spaces** for indentation consistently across the entire project. \n\n2. **Naming Conventions**:\n   - **Classes**: Use **Snake_Case** for class names.\n   - **File Names**: Class header files should be named to match the class, in **snake_case**. For example, for a `TestClass`, the header file should be `test_class.hpp` or `test_class.h`, and the corresponding source file should be `test_class.cpp`.\n   - **Function and Variable Names**: Use **snake_case** for function and variable names, even in templated code.\n   - **Parameters**: Parameters should be named in **snake_case**, even when variadic templates are used.\n\n3. **Memory Management**:\n   - Use **RAII** (Resource Acquisition Is Initialization) where applicable, especially when managing resources (e.g., in the `Pool` class).\n   - Ensure that **smart pointers** (e.g., `std::unique_ptr`, `std::shared_ptr`) or manual management are used for memory handling.\n   - Avoid `new` and `delete` directly. Use smart pointers for automatic resource management where possible.\n\n4. **Output Guidelines**:\n   - All output must be directed to **standard output** using `std::cout`.\n   - Every output message must **end with a newline character** (`\\n`).\n\n5. **Include Guards**:\n   - All header files must have include guards to prevent multiple inclusions.\n   - Example: \n     ```cpp\n     #ifndef FILENAME_HPP\n     #define FILENAME_HPP\n     // content of the header file\n     #endif // FILENAME_HPP\n     ```\n\n6. **External Libraries**:\n   - Only **standard C++ libraries** are allowed, **no external libraries** (e.g., Boost, etc.).\n   - Do not use any `*alloc()` or `free()` functions. Use modern C++ features to manage memory and resources safely.\n\n7. **Documentation**:\n   - Use **Doxygen-style comments** for generating documentation.\n   - **Markdown syntax** should be used in documentation for better clarity (supported by Sphinx).\n   - Include detailed sections in function documentation for:\n     - **Parameters**: Description of the function parameters.\n     - **Return**: What the function returns.\n     - **Throws**: Exceptions that may be thrown.\n     - **Errors**: Any potential errors that can arise.\n     - **Description**: General description of the function.\n     - **Examples**: Provide examples demonstrating usage.\n   - Follow **Google C++ Style Guide** for consistent code formatting and documentation structure.\n\n---\n\n### Documentation Structure\n\n#### 1. **File-Level Documentation**:\n   - Every header file should have a brief description at the top outlining the file's purpose and the classes or functions it contains.\n\n   Example:\n   ```cpp\n   /**\n    * @file my_class.hpp\n    * @brief Contains the definition of the MyClass class.\n    *\n    * This file declares the `MyClass` class and its member functions.\n    */\n   ```\n\n#### 2. **Class-Level Documentation**:\n   - Document the class purpose, its members, and methods.\n   - Provide a list of important methods, their purposes, and usage examples.\n\n   Example:\n   ```cpp\n   /**\n    * @class MyClass\n    * @brief This class represents a simple example class.\n    *\n    * The `MyClass` class is an example of how to document a class with its constructor,\n    * member functions, and member variables.\n    */\n   ```\n\n#### 3. **Method-Level Documentation**:\n   - Each method should have detailed comments explaining its purpose, parameters, exceptions it throws, and its return value.\n\n   Example:\n   ```cpp\n   /**\n    * @brief A method that adds two numbers.\n    *\n    * This method takes two integers, adds them, and returns the result.\n    *\n    * @param a First number to add.\n    * @param b Second number to add.\n    * @return The sum of `a` and `b`.\n    *\n    * ## Example:\n    * ```cpp\n    * MyClass obj;\n    * int result = obj.add(2, 3);  // result = 5\n    * ```\n    */\n   ```\n\n---\n\n### Makefile Integration\n\nThe Makefile simplifies the documentation generation by integrating both the Doxygen and Sphinx steps:\n- **Automatic Documentation Generation**: The Makefile contains a catch-all rule at the end, which runs `doxygen` followed by a Sphinx build command when any unknown target (e.g., `make html`) is called. This avoids the need for a separate script to build the docs.\n- **Cleaning Rules**: The `clean` and `fclean` rules also clean up documentation files (`xml` and `_build` folders).\n\nExample of generating HTML documentation with Sphinx:\n```bash\nmake html\n```\nThis command will:\n1. Run Doxygen to generate XML files in the `xml` folder.\n2. Use Sphinx to convert the XML data into HTML documentation, available in `_build/html`.\n\n---\n\n## Cleaning Up\n\nTo maintain a clean working directory, the Makefile offers the following cleaning targets:\n- **`make clean`**: Removes all object files and temporary files generated during documentation creation.\n- **`make fclean`**: Removes all generated files, including object files, the compiled library (`libftpp`), and documentation output files in `xml`.\n\n---\n\n## Notes\n\n- **Valgrind Usage**: `make valgrind-%` allows you to run tests with Valgrind for memory analysis. You can pass arguments to `valgrind` by setting the `%_ARGS` environment variable.\n- **Color-Coded Output**: The Makefile includes color-coded output for better readability in the terminal.\n\nThis setup ensures a streamlined workflow for compiling, testing, and documenting `libftpp`. Documentation is fully automated with the integration of Doxygen and Sphinx, making it easy to maintain and distribute.\n\n---\n\nEnjoy coding with `libftpp`!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F42-course%2Flibftpp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F42-course%2Flibftpp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F42-course%2Flibftpp/lists"}