improve guides (cieslarmichal#634)

CONTRIBUTING.md

@@ -1,38 +1,41 @@
 # How to contribute
 
-
 ## Getting Started
 
 Before you can build the project, you'll need to set up your development environment. Here are the steps to get started:
 
 1. **Install the required software:**
 
-    This project requires CMake and a C++ compiler with C++20 standard supported. You can check what
-    compiler has C++20 at [cppreference](https://en.cppreference.com/w/cpp/compiler_support/20).
+   This project requires CMake and a C++ compiler with C++20 standard supported. You can check what
+   compiler has C++20 at [cppreference](https://en.cppreference.com/w/cpp/compiler_support/20).
 
-    You can install these required tools on Ubuntu with the following command:
+   You can install these required tools on Ubuntu with the following command:
 
     ```sh
     sudo apt-get install cmake g++
     ```
 
-    If you're using a different operating system, you'll need to install these tools in a way that's appropriate for your system.
+   If you're using a different operating system, you'll need to install these tools in a way that's appropriate for your
+   system.
 
 2. **Clone the forked repository:**
 
-    In order to send contributions, first you need to [Fork](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo) the repository on GitHub
+   In order to send contributions, first you need
+   to [Fork](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo)
+   the repository on GitHub
 
-    So, you can clone the repository with the following command:
+   So, you can clone the repository with the following command:
 
     ```sh
     git clone https://github.com/<yourusername>/faker-cxx.git
     ```
 
-    Replace `yourusername` with the correct values for this project.
+   Replace `yourusername` with the correct values for this project.
 
 3. **Get into a discussion:**
 
-    Pick an issue from [issues](https://github.com/cieslarmichal/faker-cxx/issues) or you can refactor the code or implement features that you find useful.
+   Pick an issue from [issues](https://github.com/cieslarmichal/faker-cxx/issues) or you can refactor the code or
+   implement features that you find useful.
 
 ## Making Changes
 
@@ -42,44 +45,61 @@ Before you can build the project, you'll need to set up your development environ
   git checkout -b feature/feature-name
   ```
 
-  Please avoid working directly on the ``main`` branch.
+Please avoid working directly on the ``main`` branch.
 
 2. **Follow the code style guide:**
 
-    This project uses a `.clang-format` file to define its coding style. This file is automatically used by the `clang-format` tool to format code.
+   This project uses a `.clang-format` file to define its coding style. This file is automatically used by
+   the `clang-format` tool to format code.
 
-    The `.clang-format` file ensures that all code adheres to the project's coding style, providing consistency across the codebase. It includes settings for various formatting rules, such as indentation, spacing, and alignment.
+   The `.clang-format` file ensures that all code adheres to the project's coding style, providing consistency across
+   the codebase. It includes settings for various formatting rules, such as indentation, spacing, and alignment.
 
-    Before making changes, make sure you have `clang-format` installed. If you're using Visual Studio Code, you can install the `clang-format` extension.
+   Before making changes, make sure you have `clang-format` installed. If you're using Visual Studio Code, you can
+   install the `clang-format` extension.
 
-    When you make a commit, `pre-commit` will automatically run `clang-format` on your code, ensuring it adheres to the project's coding style.
+   When you make a commit, `pre-commit` will automatically run `clang-format` on your code, ensuring it adheres to the
+   project's coding style.
 
 3. **Set up pre-commit hooks:**
 
-    This project uses `pre-commit` hooks with `clang-format` to ensure code style consistency. Before making changes, set up the pre-commit hooks with the following commands:
+   This project uses `pre-commit` hooks with `clang-format` to ensure code style consistency. Before making changes, set
+   up the pre-commit hooks with the following commands:
 
     ```sh
     pip install pre-commit
     pre-commit install
     ```
 
-    Now, `pre-commit` will automatically run `clang-format` on your code whenever you make a commit, ensuring it adheres to the project's coding style.
+   Now, `pre-commit` will automatically run `clang-format` on your code whenever you make a commit, ensuring it adheres
+   to the project's coding style.
 
 4. **Make commits of logical units:**
 
-    This means that each commit should contain a complete and coherent piece of work that can be understood independently of other changes. For example, if you're fixing two different bugs, it's better to make two separate commits (one for each bug) rather than one commit that contains fixes for both bugs. This makes it easier to understand the purpose of each commit, and allows each change to be reviewed and applied separately.
+   This means that each commit should contain a complete and coherent piece of work that can be understood independently
+   of other changes. For example, if you're fixing two different bugs, it's better to make two separate commits (one for
+   each bug) rather than one commit that contains fixes for both bugs. This makes it easier to understand the purpose of
+   each commit, and allows each change to be reviewed and applied separately.
 
 5. **Make sure you have added the necessary tests for your changes:**
 
-    If you're adding a new feature or changing existing functionality, it's important to update or add tests that verify your changes. This helps to ensure that your changes work as expected and don't introduce new bugs. It also helps other developers understand what your code is supposed to do.
+   If you're adding a new feature or changing existing functionality, it's important to update or add tests that verify
+   your changes. This helps to ensure that your changes work as expected and don't introduce new bugs. It also helps
+   other developers understand what your code is supposed to do.
 
 6. **Run all the tests to assure nothing else was accidentally broken:**
 
-    Before you submit your changes, you should run all of the project's tests to make sure your changes haven't inadvertently broken anything. Even if you think your changes are isolated, there could be unexpected interactions with other parts of the codebase.
+   Before you submit your changes, you should run all the project's tests to make sure your changes haven't
+   inadvertently broken anything. Even if you think your changes are isolated, there could be unexpected interactions
+   with other parts of the codebase.
 
-7. **If you've added a new file to your project with non-Latin characters, ensure that the file encoding is set to Unicode (UTF-8 without signature) - Codepage 65001 in Microsoft Visual Studio Code:**
+7. **If you've added a new file to your project with non-Latin characters, ensure that the file encoding is set to
+   Unicode (UTF-8 without signature) - Codepage 65001 in Microsoft Visual Studio Code:**
 
-    If a file contains non-Latin characters (such as characters from Chinese, Arabic, or many other non-Latin alphabets), it's important to save the file with the correct encoding to ensure that the characters are displayed correctly. In Visual Studio Code, you can set the encoding for a file by clicking on the "UTF-8" button in the status bar at the bottom of the window, and then selecting "Save with Encoding" and choosing "UTF-8 without BOM".
+   If a file contains non-Latin characters (such as characters from Chinese, Arabic, or many other non-Latin alphabets),
+   it's important to save the file with the correct encoding to ensure that the characters are displayed correctly. In
+   Visual Studio Code, you can set the encoding for a file by clicking on the "UTF-8" button in the status bar at the
+   bottom of the window, and then selecting "Save with Encoding" and choosing "UTF-8 without BOM".
 
 ## Building and Testing the Project
 
@@ -98,7 +118,8 @@ Follow the steps below to build the project:
 
 2. **Configure the build using the desired preset:**
 
-    Presets are predefined sets of configuration options. This project has a preset for each compiler. To list the available presets, use the following command:
+   Presets are predefined sets of configuration options. This project has a preset for each compiler. To list the
+   available presets, use the following command:
 
     ```sh
     cmake --list-presets
@@ -110,26 +131,29 @@ Follow the steps below to build the project:
     "windows-msvc-release"   - msvc Debug
     ```
 
+   For instance, if you are in Ubuntu and want to build using GCC in Debug mode, you should use the
+   preset `unixlike-gcc-debug`. The `unixlike-clang-` preset should work for both Linux and macOS when using the CLang
+   compiler.
 
-    For instance, if you are in Ubuntu and want to build using GCC in Debug mode, you should use the preset `unixlike-gcc-debug`. The `unixlike-clang-` preset should work for both Linux and macOS when using the CLang compiler.
-
-    The `-S .` option in the following command specifies the source directory:
+   The `-S .` option in the following command specifies the source directory:
 
     ```sh
     cmake -S . --preset unixlike-gcc-debug
     ```
-3. **Build the project:**
 
-    The following command generates the build files and compiles the project using the settings specified in the `unixlike-gcc-debug` preset:
+3. **Build the project:**
 
+   The following command generates the build files and compiles the project using the settings specified in
+   the `unixlike-gcc-debug` preset:
 
     ```sh
     cmake --build --preset unixlike-gcc-debug
     ```
 
 ### Testing the Project
 
-After building the project, you can run the tests to ensure everything is working correctly. We use CTest for running tests. Follow the steps below to test the project:
+After building the project, you can run the tests to ensure everything is working correctly. We use CTest for running
+tests. Follow the steps below to test the project:
 
 **1. Run the tests using the same preset:**
 
@@ -139,45 +163,55 @@ After building the project, you can run the tests to ensure everything is workin
 
 ## Submitting Changes
 
-Once you've made your changes and ensured they adhere to the project's coding style and pass all tests, you can submit them for review. Here's how:
+Once you've made your changes and ensured they adhere to the project's coding style and pass all tests, you can submit
+them for review. Here's how:
 
 1. **Push your changes:**
 
-    First, you'll need to push your changes to the branch in your fork of the repository. You can do this with the following command:
+   First, you'll need to push your changes to the branch in your fork of the repository. You can do this with the
+   following command:
 
     ```sh
     git push origin your-branch-name
     ```
 
-    Replace `your-branch-name` with the name of the branch you created for your changes.
+   Replace `your-branch-name` with the name of the branch you created for your changes.
 
 2. **Create a pull request:**
 
-    After pushing your changes, you'll need to create a pull request. This is a way of proposing your changes to the project maintainers and allowing them to review your code.
+   After pushing your changes, you'll need to create a pull request. This is a way of proposing your changes to the
+   project maintainers and allowing them to review your code.
 
-    To create a pull request, go to the main page of the repository on GitHub, and click on the "Pull requests" tab. Then click on the "New pull request" button.
+   To create a pull request, go to the main page of the repository on GitHub, and click on the "Pull requests" tab. Then
+   click on the "New pull request" button.
 
-    In the "base" dropdown, select the main branch of the original repository, and in the "compare" dropdown, select the branch in your fork with your changes.
+   In the "base" dropdown, select the main branch of the original repository, and in the "compare" dropdown, select the
+   branch in your fork with your changes.
 
-    Fill out the pull request form with a title and description that explain your changes, and then click "Create pull request".
+   Fill out the pull request form with a title and description that explain your changes, and then click "Create pull
+   request".
 
-    For more detailed instructions, see GitHub's guide on [creating a pull request from a fork](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork).
+   For more detailed instructions, see GitHub's guide
+   on [creating a pull request from a fork](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork).
 
 # Additional Resources
 
 To assist you in contributing to the project, we've compiled a list of useful resources:
 
 1. **Community Support:**
 
-    If you have any questions or need help understanding a feature, feel free to join our [Discord Channel](https://discord.com/invite/h2ur8H6mK6). It's a great place to connect with other contributors and get answers to your questions.
+   If you have any questions or need help understanding a feature, feel free to join
+   our [Discord Channel](https://discord.com/invite/h2ur8H6mK6). It's a great place to connect with other contributors
+   and get answers to your questions.
 
 2. **Reference Implementations:**
 
-    If you're implementing a feature, you might find it helpful to look at [Faker.js](https://github.com/faker-js/faker). It's a similar project in JavaScript, and its implementations could serve as a useful reference.
+   If you're implementing a feature, you might find it helpful to look at [Faker.js](https://github.com/faker-js/faker).
+   It's a similar project in JavaScript, and its implementations could serve as a useful reference.
 
 3. **CMake and CTest Documentation:**
 
-    If you're new to CMake and CTest, or if you need a refresher, check out their official documentation:
+   If you're new to CMake and CTest, or if you need a refresher, check out their official documentation:
 
     - [CMake Documentation](https://cmake.org/cmake/help/latest/index.html)
     - [CTest Documentation](https://cmake.org/cmake/help/latest/manual/ctest.1.html)

Doxyfile

@@ -60,7 +60,7 @@ PROJECT_BRIEF          =
 # pixels and the maximum width should not exceed 200 pixels. Doxygen will copy
 # the logo to the output directory.
 
-PROJECT_LOGO           = docs/images/logo.png
+PROJECT_LOGO           = docs/public/logo.png
 
 # The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) path
 # into which the generated documentation will be written. If a relative path is

ExternalLicenses.md → LICENSES.md

@@ -1,4 +1,6 @@
-# flexxxxer/md5_hash:
+# Third Party Licenses
+
+## flexxxxer/md5_hash:
 
 MIT License
 
@@ -22,7 +24,7 @@ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 
-# System-Glitch/SHA256:
+## System-Glitch/SHA256:
 
 MIT License
 
@@ -46,7 +48,7 @@ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 
-# faker-js/faker:
+## faker-js/faker:
 
 Faker - Copyright (c) 2022-2023
 

README.md

@@ -112,20 +112,11 @@ int main()
 
 ## Compiler support
 
-Use one of these compilers when working with Faker C++.
-
 - [MSVC➚](https://en.wikipedia.org/wiki/Microsoft_Visual_Studio) version 143 or newer.
 - [GCC➚](https://gcc.gnu.org/) version 12 or newer.
 - [Clang➚](https://clang.llvm.org/) version 16 or newer.
 - [Apple Clang➚](https://clang.llvm.org/) version 16 or newer.
 
-If you have any confusion please refer to the respective guides.
-
-- [Clang++](./docs/guides/clang-compilation-guide.md)
-- [Apple Clang++](./docs/guides/apple-clang-compilation-guide.md)
-- [G++](./docs/guides/gcc-compilation-guide.md)
-- [MSVC](./docs/guides/msvc-compilation-guide.md)
-
 ## Dependencies
 
 - GTest (set `BUILD_TESTING=OFF` CMake flag to disable this dependency)
@@ -156,6 +147,13 @@ To build the library with Conan, follow the steps below:
 
 We would love it if you contributed to Faker C++! 🚀
 
+Check our guides on how to build the project locally:
+
+- [Clang++](./docs/guides/clang-compilation-guide.md)
+- [Apple Clang++](./docs/guides/apple-clang-compilation-guide.md)
+- [G++](./docs/guides/gcc-compilation-guide.md)
+- [MSVC](./docs/guides/msvc-compilation-guide.md)
+
 Before contributing please review
 our [CONTRIBUTING](https://github.com/cieslarmichal/faker-cxx/blob/main/CONTRIBUTING.md) guide.
 

docs/guides/apple-clang-compilation-guide.md

@@ -1,44 +1,45 @@
-## 🔨 Building project with Apple Clang 16
+# 🔨 Building project with Apple Clang
 
-### 1. Install Clang 16
+## 1. Install Apple Clang
 
 ```bash
-brew install llvm@16
+brew install llvm@18
 ```
 
-### 2. Prepare build directory
+and add compiler to path:
+
+```bash
+export PATH="/opt/homebrew/opt/llvm@18/bin:$PATH"
+```
+
+## 2. Prepare build directory
 
 ```bash
 git clone https://github.com/cieslarmichal/faker-cxx.git
 cd faker-cxx
 git submodule update --init --recursive
-mkdir build && cd build
 ```
 
-### 3. Setup CMake
+## 3. Setup CMake
 
 ```bash
-cmake .. -DCMAKE_CXX_COMPILER=/opt/homebrew/opt/llvm@16/bin/clang++
+cmake -B ./build -DCMAKE_CXX_COMPILER=clang++ -DBUILD_TESTING=ON
 ```
 
-⚠️ **Warning:** Ensure that the path `/opt/homebrew/opt/llvm@16/bin/clang++` is valid on your system. If this path is
-not correct, replace it with the correct path to your Clang 16 compiler. You can find the correct path by using the
-command `brew --prefix llvm@16`. Adjust the CMake command accordingly.
-
-### 4. Build
+## 4. Build
 
 ```bash
-make
+cmake --build ./build
 ```
 
-### 5. Run tests
+## 5. Run tests
 
 ```bash
 ./faker-cxx-UT
 ```
 
----
+or using CTest:
 
-**Note:** This guide assumes a standard installation of Homebrew and the default paths it uses. If your Homebrew or LLVM
-installation paths are different, you will need to adjust the commands accordingly. Remember that paths and specific
-commands might vary depending on your system configuration and the versions of the tools installed.
+```bash
+ctest --test-dir ./build
+```