From 5fff13261157e6de55bcfd5ccbf505115fb3fbfa Mon Sep 17 00:00:00 2001 From: Ilya Churaev Date: Fri, 23 Sep 2022 15:35:12 +0400 Subject: [PATCH] Dev doc guide (#13163) * Add developer guide for the documentation * Update dev_doc_guide.md * Update CI trigger rules * Fixed CI run * Fixed CI trigers * Disable trigger for .ci * Revert "Disable trigger for .ci" This reverts commit a5770a61bc50f9b2457f3f8d8012113e0c1e5d90. * Update docs/dev/dev_doc_guide.md Co-authored-by: Tatiana Savina * Update docs/dev/dev_doc_guide.md Co-authored-by: Tatiana Savina * Update docs/dev/dev_doc_guide.md Co-authored-by: Tatiana Savina * Update docs/dev/dev_doc_guide.md Co-authored-by: Tatiana Savina * Update docs/dev/dev_doc_guide.md Co-authored-by: Tatiana Savina * Update docs/dev/dev_doc_guide.md Co-authored-by: Tatiana Savina * Update docs/dev/dev_doc_guide.md Co-authored-by: Tatiana Savina * Update docs/dev/dev_doc_guide.md Co-authored-by: Tatiana Savina * Update docs/dev/dev_doc_guide.md Co-authored-by: Tatiana Savina * Update docs/dev/dev_doc_guide.md Co-authored-by: Tatiana Savina * Update docs/dev/dev_doc_guide.md Co-authored-by: Tatiana Savina * Update docs/dev/index.md Co-authored-by: Tatiana Savina * Update docs/dev/index.md Co-authored-by: Tatiana Savina * Update docs/dev/dev_doc_guide.md Co-authored-by: Tatiana Savina * Update docs/dev/dev_doc_guide.md Co-authored-by: Tatiana Savina --- docs/dev/dev_doc_guide.md | 96 +++++++++++++++++++++++++++++++++++++++ docs/dev/index.md | 34 ++++++++------ 2 files changed, 117 insertions(+), 13 deletions(-) create mode 100644 docs/dev/dev_doc_guide.md diff --git a/docs/dev/dev_doc_guide.md b/docs/dev/dev_doc_guide.md new file mode 100644 index 00000000000..02082315031 --- /dev/null +++ b/docs/dev/dev_doc_guide.md @@ -0,0 +1,96 @@ +# Creating developer documentation + +Developer documentation provides an overview of the component development and helps engineers understand the underlying technology. +This guide contains the requirements for writing developer documentation. + + +## The component structure + +The OpenVINO component structure is fully defined in the [dedicated section of developer documentation](./index.md#openvino-component-structure). +This guide highlights the parts which are used for developer documentation. The structure is presented below: + +``` +openvino_component/ + docs/ // Contains detailed component documentation + README.md // Endtry point for the developer documentation +``` + +## ***README.md*** content + +README.md provides an entry point to the component documentation. Here are the best practices for writing a good README.md: + +- Include only the necessary information. Avoid overloading the document with excessive details. +- Make sure your document has a clear structure, is easy to navigate and quickly look through. +- Provide links to additional documentation and resources. + +You can use the following template for a README.md file: +```md +# Component name + +Short information about the component. + * Responsibility + * Supported features + * Code style + +## Key contacts + +The section provides information about groups of developers who can help in case of questions, and also review and merge PRs. + +## Components + +The section contains basic information about the included components: API, sources, tests, etc. +Detailed information can be located in the `docs/` folder. This section can contain links to these pages. + +## Architecture + +Is an optional section which provides main ideas about the component architecture. +It can contain references to the pages with additional information. + +## Tutorials + +The section contains a list of component tutorials. +Example: + * [How to support new operation](./docs/operation_support.md) + * [How to implement new feature](./docs/new_feature.md) + * [How to debug the component](./docs/debug_capabilities.md) + * ... + +## See also + +The section contains a list of related pages. +Example: + * [OpenVINO™ README](../../README.md) + * [Developer documentation](../../docs/dev/index.md) + * ... +``` + +## ***docs/*** folder content + +Docs folder should contain pages with a detailed description of the component features and media content for the developer documentation. Make sure that the pages in this folder provide information directly related to the topic. It is better to provide information about additional topics in a separate file and make a reference to it. + +## Media content +The developer documentation may include pictures, diagrams, and examples that illustrate the described features to make it easier to understand. +It is recommended to use the `mermaid` framework for diagrams. Read the [Github Documentation](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-diagrams) to get more information. The framework allows creating diagrams and pasting them to your documents. For example, the code: + +````md +```mermaid +graph LR; + A-->B; + A-->C; + B-->D; + C-->D; +``` +```` + +Generates the next diagram: +```mermaid +graph LR; + A-->B; + A-->C; + B-->D; + C-->D; +``` + +## See also + * [OpenVINO™ README](../../README.md) + * [Developer documentation](./index.md) diff --git a/docs/dev/index.md b/docs/dev/index.md index 44215ca8433..31d5b03a1ad 100644 --- a/docs/dev/index.md +++ b/docs/dev/index.md @@ -61,24 +61,14 @@ flowchart LR * [Add new operation](../../src/core/docs/operation_enabling_flow.md) * [Add new transformation](#todo) * [Get code coverage report](./test_coverage.md) + * [Add component developer documentation](./dev_doc_guide.md) * [OpenVINO contribution guideline](../../CONTRIBUTING.md) * [OpenVINO Debug Capabilities](./debug_capabilities.md) ## OpenVINO repository structure -The trend in the organization of structure repository is the idea that components should contain all dependencies inside (like thirdparty, testts, documentation and etc.). Below the abstract component structure is presented with comments and marks for optional folders. -``` -ov_component/ // Component folder - cmake/ // (optional) CMake scripts which are related only for this component - dev_api/ // (optional) Developer API is used in case if component wants to provide some API for internal developers - docs/ // (optional) Contains detailed component documentation - include/ // (optional) Public component API - src/ // Sources of the component - tests/ // Tests on the component - thirdparty/ // (optional) Third-party dependencies - CMakeLists.txt // Main CMake script - README.md // (optional) Endtry point for the developer documentation -``` +The repository is organized in such a way that the components contain all dependencies inside (for example, thirdparty, tests, documentation, and other). +With this approach, groups of developers, who are concentrated on different components, can efficiently work together. The OpenVINO Repository compositions from next components, click on the component name to get more information about it: 
@@ -98,6 +88,24 @@ The OpenVINO Repository compositions from next components, click on the componen
+### OpenVINO Component Structure + +The OpenVINO component should contain all dependencies inside (for example, thirdparty, tests, documentation, and other). The abstract component structure with comments and marks for optional folders is presented below. + +``` +ov_component/ // Component folder + cmake/ // (optional) CMake scripts which are related only for this component + dev_api/ // (optional) Developer API is used in case if component wants to provide some API for internal developers + docs/ // (optional) Contains detailed component documentation + include/ // (optional) Public component API + src/ // Sources of the component + tests/ // Tests on the component + thirdparty/ // (optional) Third-party dependencies + CMakeLists.txt // Main CMake script + README.md // (optional) Endtry point for the developer documentation +``` + + ## Features * [Conditional Compilation](./conditional_compilation.md)