Merge pull request #685 from lukaszstolarczuk/revamp-readme

[UR] Revamp README file a little

README.md

@@ -1,14 +1,29 @@
 # Unified Runtime
 
-[![GHA build status](https://github.com/oneapi-src/unified-runtime/actions/workflows/cmake.yml/badge.svg?branch=main)](https://github.com/oneapi-src/unified-runtime/actions)
+[![Build and test](https://github.com/oneapi-src/unified-runtime/actions/workflows/cmake.yml/badge.svg)](https://github.com/oneapi-src/unified-runtime/actions/workflows/cmake.yml)
+[![CodeQL](https://github.com/oneapi-src/unified-runtime/actions/workflows/codeql.yml/badge.svg)](https://github.com/oneapi-src/unified-runtime/actions/workflows/codeql.yml)
+[![Bandit](https://github.com/oneapi-src/unified-runtime/actions/workflows/bandit.yml/badge.svg)](https://github.com/oneapi-src/unified-runtime/actions/workflows/bandit.yml)
 
-> **Note**
->
-> For those who intend to make a contribution to the project please read our
-> [Contribution Guide](https://oneapi-src.github.io/unified-runtime/core/CONTRIB.html)
-> for more information.
+<!-- TODO: add general description and purpose of the project -->
 
-## Contents
+## Table of contents
+
+1. [Contents of the repo](#contents-of-the-repo)
+2. [Integration](#integration)
+    - [Weekly tags](#weekly-tags)
+3. [Third-Party tools](#third-party-tools)
+4. [Building](#building)
+    - [Windows](#windows)
+    - [Linux](#linux)
+    - [CMake standard options](#cmake-standard-options)
+    - [Additional make targets](#additional-make-targets)
+5. [Contributions](#contributions)
+    - [Adapter naming convention](#adapter-naming-convention)
+    - [Source code generation](#source-code-generation)
+    - [Documentation](#documentation)
+
+
+## Contents of the repo
 
 This repo contains the following:
 
@@ -41,55 +56,45 @@ add_executable(example example.cpp)
 target_link_libraries(example PUBLIC unified-runtime::headers)
 ```
 
-### Weekly Tags
+### Weekly tags
 
 Each Friday at 23:00 UTC time a [prerelease
 tag](https://github.com/oneapi-src/unified-runtime/releases) is created which
 takes the form `weekly-YYYY-MM-DD`. These tags should be used by downstream
 projects which intend to track development closely but maintain a fixed point in
 history to avoid pulling potentially breaking changes from the `main` branch.
 
-## Source Code Generation
-
-Code is generated using included [Python scripts](/scripts/README.md).
-
-## Documentation
-
-Documentation is generated from source code using Sphinx.
-
-## Third-Party Tools
+## Third-Party tools
 
 Tools can be acquired via instructions in [third_party](/third_party/README.md).
 
 ## Building
 
 Requirements:
 - C++ compiler with C++17 support
-- cmake >= 3.14.0
+- [CMake](https://cmake.org/) >= 3.14.0
 - clang-format-15.0 (can be installed with `python -m pip install clang-format==15.0.7`)
 
-Project is defined using [CMake](https://cmake.org/).
-
-**Windows**:
+### Windows
 
-Generating Visual Studio Project.  EXE and binaries will be in **build/bin/{build_config}**
+Generating Visual Studio Project. EXE and binaries will be in **build/bin/{build_config}**
 
-~~~~
+```bash
 $ mkdir build
 $ cd build
 $ cmake {path_to_source_dir} -G "Visual Studio 15 2017 Win64"
-~~~~
+```
 
-**Linux**:
+### Linux
 
 Executable and binaries will be in **build/bin**
 
-~~~~
+```bash
 $ mkdir build
 $ cd build
 $ cmake {path_to_source_dir}
 $ make
-~~~~
+```
 
 ### CMake standard options
 
@@ -98,32 +103,36 @@ List of options provided by CMake:
 | Name | Description | Values | Default |
 | - | - | - | - |
 | UR_BUILD_TESTS | Build the tests | ON/OFF | ON |
+| UR_BUILD_TOOLS | Build tools | ON/OFF | ON |
 | UR_FORMAT_CPP_STYLE | Format code style | ON/OFF | OFF |
 | UR_DEVELOPER_MODE | Treat warnings as errors and enables additional checks | ON/OFF | OFF |
 | UR_USE_ASAN | Enable AddressSanitizer | ON/OFF | OFF |
 | UR_USE_UBSAN | Enable UndefinedBehavior Sanitizer | ON/OFF | OFF |
 | UR_USE_MSAN | Enable MemorySanitizer (clang only) | ON/OFF | OFF |
 | UR_ENABLE_TRACING | Enable XPTI-based tracing layer | ON/OFF | OFF |
-| UR_BUILD_TOOLS | Build tools | ON/OFF | ON |
 
-**General**:
+### Additional make targets
+
+To run automated code formatting, configure CMake with `UR_FORMAT_CPP_STYLE` option
+and then run a custom `cppformat` target:
 
-To run automated code formatting build with option `UR_FORMAT_CPP_STYLE` and then run a custom `cppformat` target:
-~~~~
+```bash
 $ make cppformat
-~~~~
+```
 
-If you've made modifications to the specification, you can also run a custom `generate-code` or `generate` target prior to building.
-This call will generate the source code:
-~~~~
-$ make generate-code
-~~~~
+If you've made modifications to the specification, you can also run
+a custom `generate` target prior to building.
+It will generate the source code **and** run automated code formatting:
 
-This call will generate the source code and run automated code formatting:
-~~~~
+```bash
 $ make generate
-~~~~
-Note: `generate` target requires `UR_FORMAT_CPP_STYLE` to bet set.
+```
+
+## Contributions
+
+For those who intend to make a contribution to the project please read our
+[Contribution Guide](https://oneapi-src.github.io/unified-runtime/core/CONTRIB.html)
+for more information.
 
 ### Adapter naming convention
 
@@ -132,3 +141,12 @@ to use the following naming convention:
 
 * On Linux platforms, use `libur_adapter_[name].so`.
 * On Windows platforms, use `ur_adapter_[name].dll`.
+
+### Source code generation
+
+Code is generated using included [Python scripts](/scripts/README.md).
+
+### Documentation
+
+Documentation is generated from source code using Sphinx -
+see [scripts dir](/scripts/README.md) for details.

scripts/README.md

@@ -4,12 +4,10 @@ Python dependencies:
   * [PyYAML](https://pyyaml.org/) v3.13
   * [Sphinx](https://www.sphinx-doc.org/en/master/) v2.2.2
 
-Installing Python dependencies:
-  ~~~~
-  * Install all python requirements.
-  ~~~~
-    python -m pip install -r ../third_party/requirements.txt
-  ~~~~
+To install all Python dependencies, execute:
+```bash
+$ python -m pip install -r ../third_party/requirements.txt
+```
 
 Documentation is generated from source code using Doxygen.  
   * [Doxygen](http://www.doxygen.nl/) v1.8.15