diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index 76358fec..ec4450af 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -14,22 +14,22 @@ race, religion, or sexual identity and orientation. Examples of behavior that contributes to creating a positive environment include: -* Using welcoming and inclusive language -* Being respectful of differing viewpoints and experiences -* Gracefully accepting constructive criticism -* Focusing on what is best for the community -* Showing empathy towards other community members +* Using welcoming and inclusive language +* Being respectful of differing viewpoints and experiences +* Gracefully accepting constructive criticism +* Focusing on what is best for the community +* Showing empathy towards other community members Examples of unacceptable behavior by participants include: -* The use of sexualized language or imagery and unwelcome sexual attention or - advances -* Trolling, insulting/derogatory comments, and personal or political attacks -* Public or private harassment -* Publishing others' private information, such as a physical or electronic - address, without explicit permission -* Other conduct which could reasonably be considered inappropriate in a - professional setting +* The use of sexualized language or imagery and unwelcome sexual attention or + advances +* Trolling, insulting/derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or electronic + address, without explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting ## Our Responsibilities @@ -69,13 +69,12 @@ dispute. If you are unable to resolve the matter for any reason, or if the behavior is threatening or harassing, report it. We are dedicated to providing an environment where participants feel welcome and safe. -Reports should be directed to *[PROJECT STEWARD NAME(s) AND EMAIL(s)]*, the -Project Steward(s) for *[PROJECT NAME]*. It is the Project Steward’s duty to -receive and address reported violations of the code of conduct. They will then -work with a committee consisting of representatives from the Open Source -Programs Office and the Google Open Source Strategy team. If for any reason you -are uncomfortable reaching out to the Project Steward, please email -opensource@google.com. +Reports should be directed to the libhal email. It is the Project Steward’s +duty to receive and address reported violations of the code of conduct. They +will then work with a committee consisting of representatives from the Open +Source Programs Office and the Google Open Source Strategy team. If for any +reason you are uncomfortable reaching out to the Project Steward, please email +libembeddedhal@google.com. We will investigate every complaint, but you may not receive a direct response. We will use our discretion in determining when and how to follow up on reported diff --git a/README.md b/README.md index d80c11d9..3b64357e 100644 --- a/README.md +++ b/README.md @@ -4,11 +4,20 @@ Organization wide repo for docs, assets, and tools any other static information. ## Updating the docs -libhal uses [mkdocs-material](https://squidfunk.github.io/mkdocs-material/) for our static documentation and [sphinx](https://www.sphinx-doc.org/en/master/) for our API documentation +libhal uses [mkdocs-material](https://squidfunk.github.io/mkdocs-material/) for +our static documentation and [sphinx](https://www.sphinx-doc.org/en/master/) +for our API documentation -If you'd like to contribute to the libhal website and documentation you can do so by quickly setting up the enviornement by running the following commands. Please note that the build script is designed for a bash environment and is intended to be used on unix-based operating systems. The documentation is fully compatible with Windows, however you will need to write your own `.bat` install script or run the commands individually (as well as switch from bash's commands to powershell or command prompt's variants of them). +If you'd like to contribute to the libhal website and documentation you can do +so by quickly setting up the enviornement by running the following commands. +Please note that the build script is designed for a bash environment and is +intended to be used on unix-based operating systems. The documentation is fully +compatible with Windows, however you will need to write your own `.bat` install +script or run the commands individually (as well as switch from bash's commands +to powershell or command prompt's variants of them). -Please first install python 3.10 or later. Then run the following to install the required packages for running the documentation. +Please first install python 3.10 or later. Then run the following to install +the required packages for running the documentation. ```bash pip install -r requirements.txt @@ -23,11 +32,12 @@ Now to actually build the documentation. > [!NOTE] > You may need to run `chmod +x build.sh` to run it. - Finally to serve the documentation: + ```bash - mkdocs serve +mkdocs serve ``` + The page should be available on this address `http://127.0.0.1:8000`. Now whenever you update the markdown in the mkdocs directory, the page will @@ -35,21 +45,27 @@ auto-reload with your changes, *however* if you are making changes to the API do If you changed just `rst` or `md` files in the `sphinx` directory you can simply run the command inside the `sphinx` directory. ```bash - sphinx-build -b html -Dbreathe_projects.libhal=../doxygen_output/xml . output +sphinx-build -b html -Dbreathe_projects.libhal=../doxygen_output/xml . output ``` + If things changed in the actual code for the documentation, you will need to build the doxygen files as well. Run the following starting in the root of this repo. ```bash - doxygen Doxyfile.in - cd sphinx - sphinx-build -b html -Dbreathe_projects.libhal=../doxygen_output/xml . output +doxygen Doxyfile.in +cd sphinx +sphinx-build -b html -Dbreathe_projects.libhal=../doxygen_output/xml . output ``` -Checkout [mkdocs-material](https://squidfunk.github.io/mkdocs-material/) for more details -on the features that can be used for the static side of this site. +Checkout [mkdocs-material](https://squidfunk.github.io/mkdocs-material/) for +more details on the features that can be used for the static side of this site. -Checkout [sphinx](https://www.sphinx-doc.org/en/master/) for how to use sphinx at a basic level, [breathe](https://breathe.readthedocs.io/en/latest/) on how to use doxygen directives on how to organize your code inside of sphinx `rst` or `md` files, and finally the [theme](https://pydata-sphinx-theme.readthedocs.io/en/stable/) for theme specific uses for the API documentation. +Checkout [sphinx](https://www.sphinx-doc.org/en/master/) for how to use sphinx +at a basic level, [breathe](https://breathe.readthedocs.io/en/latest/) on how +to use doxygen directives on how to organize your code inside of sphinx `rst` +or `md` files, and finally the +[theme](https://pydata-sphinx-theme.readthedocs.io/en/stable/) for theme +specific uses for the API documentation. ## Contributing @@ -58,10 +74,3 @@ See [`CONTRIBUTING.md`](CONTRIBUTING.md) for details. ## License Apache 2.0; see [`LICENSE`](LICENSE) for details. - -## Disclaimer - -This project is not an official Google project. It is not supported by -Google and Google specifically disclaims all warranties as to its quality, -merchantability, or fitness for a particular purpose. - diff --git a/mkdocs/contributor_guide/style.md b/mkdocs/contributor_guide/style.md index 1a9f3536..995cedc4 100644 --- a/mkdocs/contributor_guide/style.md +++ b/mkdocs/contributor_guide/style.md @@ -40,7 +40,7 @@ Guidelines](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines). ## S.2 Refrain from performing manual bit manipulation -Use `hal::bit` from `libhal-util` library to perform bitwise operations +Use `hal::bit_modify` from `libhal-util` library to perform bitwise operations operations. ## S.3 Refrain from using MACROS @@ -55,12 +55,13 @@ in writing out the boilerplate. Only use preprocessor `#if` and the like if it is impossible to use `if constexpr` to achieve the same behavior. -## S.4 Never include C++ stream libraries +## S.4 Never include C++ `` libraries Applications incur an automatic 150kB space penalty for including any of the ostream headers that also statically generate the global `std::cout` and the like objects. This happens even if the application never uses any part of -`` library. +`` library. `` can be used in libraries that will only be +used for host side testing. ## S.5 Refrain from memory allocations @@ -68,9 +69,9 @@ Interfaces and drivers should refrain from APIs that force memory allocations or implementations that allocate memory from heap. This means avoiding STL libraries that allocate such as `std::string` or `std::vector`. -Many embedded system applications, especially the real time ones, do not allow -dynamic memory allocations. There are many reasons for this that can be found -MISRA C++ and AutoSAR. +Many embedded system applications, especially the real time applications, do +not allow dynamic memory allocations. There are many reasons for this that can +be found MISRA C++ and AutoSAR. ## S.6 Drivers should not log to STDOUT or STDIN @@ -100,10 +101,10 @@ without giving control back to the application are prohibited. As an example drivers should never call: - - `std::abort()` - - `std::exit()` - - `std::terminate()` - - any of their variants +- `std::abort()` +- `std::exit()` +- `std::terminate()` +- any of their variants This includes placing an **infinite loop block** in a driver. @@ -152,7 +153,7 @@ class target { See [private virtual method](http://www.gotw.ca/publications/mill18.htm) for more details. Rationale can be found within that link as well. -## S.10 Avoid using `bool` as ... +## S.10 Avoid using `bool` as: ### S.10.1 an object member