ReactDoc - the first open source solution of the program "Common Frontal System"
Programmers always used documentation generators whenever possible. This simplifies documentation, allows you to get help on the product without referring to the code of the project itself. JavaDoc was used in the Program for a long time, because Most projects are written in Java, but this was until recently. Now projects are developing - few people represent a good product without a good UI. The industry frontend gave birth to a new direction of development - the developer of the UI. Concentrating on user friendliness rather than business processes, UI development avoids the complexity of business applications - a stumbling block for many enterprise solutions.
For a long time in this area there were no decent tools, since it is difficult to automate something that is not systematized. Over time, a tool similar to JavaDoc appeared, which even got a similar name - JSDoc. The key disadvantages include the fact that he forced to write code in a certain way, which is not always suitable for a specific project. It should be noted that the code was inflated due to the abundance of comments, which reduced the readability of the code for the development team.
Everything changed in the UI development with the advent of React. All interfaces began to be divided into atomic pieces, from which huge applications began to be assembled: each piece is isolated and covered with necessary tests. Each company has its own library of UI components, which are also called UIKit among developers.
')
In the program "Common Frontal System" we developed our own library, however, and it needed to be documented.
We started writing documentation, but quickly came to the realization that it was very labor-intensive to prepare it by hand. We lose precious time on documentation, while lagging behind in the development of the project itself. The idea was born to generate documentation directly from the code, the idea is not new, but we decided to try. We had a project on React and TypeScript. Using the poorly documented capabilities of TypeScript, we began to do our own generation for each component. All comments on each property of the component became pieces of the documentation that was output.
We did not dive deep into TypeScript roots — that would take too much time. Using typedoc, we obtained the structure of the project in the form of json, according to this structure we are mirroring the project, but already knowing the descriptions of the components themselves. For convenient loading of descriptions into the documentation itself, we have implemented a special component that “pulls out” the description from the mirrored structure and displays it on the page. It sounds difficult, but in practice it works like a clock.
Further more. We did not want to copy the code in order to display an example in the documentation and display the text of the code on which it was written. We made a separate component that output both the example and the code for this example. Using a mirrored structure, we managed to reach the connection of the examples with their source code.
We posted the solution on the largest GitHub collaborative portal so you can use our tool in your daily work. We will be glad to talk in the comments to the post.
We continue to work on improving the solution, namely:
Java developers have JavaDoc, and what do UI developers have?
For a long time in this area there were no decent tools, since it is difficult to automate something that is not systematized. Over time, a tool similar to JavaDoc appeared, which even got a similar name - JSDoc. The key disadvantages include the fact that he forced to write code in a certain way, which is not always suitable for a specific project. It should be noted that the code was inflated due to the abundance of comments, which reduced the readability of the code for the development team.
Everything changed in the UI development with the advent of React. All interfaces began to be divided into atomic pieces, from which huge applications began to be assembled: each piece is isolated and covered with necessary tests. Each company has its own library of UI components, which are also called UIKit among developers.
')
In the program "Common Frontal System" we developed our own library, however, and it needed to be documented.
We started writing documentation, but quickly came to the realization that it was very labor-intensive to prepare it by hand. We lose precious time on documentation, while lagging behind in the development of the project itself. The idea was born to generate documentation directly from the code, the idea is not new, but we decided to try. We had a project on React and TypeScript. Using the poorly documented capabilities of TypeScript, we began to do our own generation for each component. All comments on each property of the component became pieces of the documentation that was output.
How was this achieved?
We did not dive deep into TypeScript roots — that would take too much time. Using typedoc, we obtained the structure of the project in the form of json, according to this structure we are mirroring the project, but already knowing the descriptions of the components themselves. For convenient loading of descriptions into the documentation itself, we have implemented a special component that “pulls out” the description from the mirrored structure and displays it on the page. It sounds difficult, but in practice it works like a clock.
Further more. We did not want to copy the code in order to display an example in the documentation and display the text of the code on which it was written. We made a separate component that output both the example and the code for this example. Using a mirrored structure, we managed to reach the connection of the examples with their source code.
We posted the solution on the largest GitHub collaborative portal so you can use our tool in your daily work. We will be glad to talk in the comments to the post.
We continue to work on improving the solution, namely:
- By creating live reloading: you no longer need to wait for the rebuilding of the entire library to see the result in the documentation.
- Supported by JavaScript: we understand that now many projects do not use TypeScript in their projects.
- Design update: now the tool looks ascetic, but these are our first steps in open source, we promise, we will fix it!
Source: https://habr.com/ru/post/323148/
All Articles