IntenseWebs/openvino
3
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Dev doc guide (#13163)

Browse Source 
* 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 a5770a61bc.

* Update docs/dev/dev_doc_guide.md

Co-authored-by: Tatiana Savina <tatiana.savina@intel.com>

* Update docs/dev/dev_doc_guide.md

Co-authored-by: Tatiana Savina <tatiana.savina@intel.com>

* Update docs/dev/dev_doc_guide.md

Co-authored-by: Tatiana Savina <tatiana.savina@intel.com>

* Update docs/dev/dev_doc_guide.md

Co-authored-by: Tatiana Savina <tatiana.savina@intel.com>

* Update docs/dev/dev_doc_guide.md

Co-authored-by: Tatiana Savina <tatiana.savina@intel.com>

* Update docs/dev/dev_doc_guide.md

Co-authored-by: Tatiana Savina <tatiana.savina@intel.com>

* Update docs/dev/dev_doc_guide.md

Co-authored-by: Tatiana Savina <tatiana.savina@intel.com>

* Update docs/dev/dev_doc_guide.md

Co-authored-by: Tatiana Savina <tatiana.savina@intel.com>

* Update docs/dev/dev_doc_guide.md

Co-authored-by: Tatiana Savina <tatiana.savina@intel.com>

* Update docs/dev/dev_doc_guide.md

Co-authored-by: Tatiana Savina <tatiana.savina@intel.com>

* Update docs/dev/dev_doc_guide.md

Co-authored-by: Tatiana Savina <tatiana.savina@intel.com>

* Update docs/dev/index.md

Co-authored-by: Tatiana Savina <tatiana.savina@intel.com>

* Update docs/dev/index.md

Co-authored-by: Tatiana Savina <tatiana.savina@intel.com>

* Update docs/dev/dev_doc_guide.md

Co-authored-by: Tatiana Savina <tatiana.savina@intel.com>

* Update docs/dev/dev_doc_guide.md

Co-authored-by: Tatiana Savina <tatiana.savina@intel.com>
This commit is contained in:
Ilya Churaev 2022-09-23 15:35:12 +04:00 committed by GitHub
parent 6c1eb9d692
commit 5fff132611
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 117 additions and 13 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

96
docs/dev/dev_doc_guide.md Normal file
View File

@ -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)

34
docs/dev/index.md
View File

@ -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:
<pre>
@ -98,6 +88,24 @@ The OpenVINO Repository compositions from next components, click on the componen
</code>
</pre>
### 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)