ReactDoc - the first open source solution of the program "Unified Frontal System"
Programmers have always used documentation generators whenever possible. This simplifies the documentation, allows you to get help on the product without accessing the code of the project itself. The program used JavaDoc for a long time, because most projects are written in Java, but that was until recently. Now projects are developing - few people present a good product without a good UI. The frontend industry has given birth to a new direction of development - the UI developer. By focusing on user convenience rather than business processes, UI development avoids the complexity of business applications - a stumbling block for many enterprise solutions.
For a long time there were no decent tools in this area, since it is difficult to automate what is not systematized. Over time, a tool similar to JavaDoc appeared, which even got a similar name - JSDoc. His key shortcomings include the fact that he forced him to write code in a certain way, which is not always suitable for a specific project. It is worth noting that the code was bloated due to the abundance of comments, which reduced the readability of the code itself for the development team.
Everything has changed in 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 was isolated and covered with the necessary tests. Each company has its own library of UI components, which are also called UIKit among developers.
In the program "Unified Frontal System" we developed our own library, however, and it was necessary to document it.
We started writing documentation, but quickly came to the understanding that it was very laborious to prepare it manually. We lose valuable 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 features 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 displayed.
We did not dive deep into the roots of TypeScript - it would take too much time. Using typedoc, we got the project structure in the form of json, according to this structure we mirror the project, but already knowing the descriptions of the components themselves. For convenient loading of descriptions into the documentation itself, we implemented a special component that “pulls” the description from the mirrored structure and displays it on the page. It sounds complicated, but in practice it works like a clock.
Further more. We did not want to copy the code to get an example in the documentation and display the text of the code on which it was written. We made a separate component that displayed both the example and the code for this example. Using a mirrored structure, we were able to achieve a connection between the examples and their source code.
We have posteda solution on the largest GitHub collaborative development 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 JavaDocs, and what do UI developers have?
For a long time there were no decent tools in this area, since it is difficult to automate what is not systematized. Over time, a tool similar to JavaDoc appeared, which even got a similar name - JSDoc. His key shortcomings include the fact that he forced him to write code in a certain way, which is not always suitable for a specific project. It is worth noting that the code was bloated due to the abundance of comments, which reduced the readability of the code itself for the development team.
Everything has changed in 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 was isolated and covered with the necessary tests. Each company has its own library of UI components, which are also called UIKit among developers.
In the program "Unified Frontal System" we developed our own library, however, and it was necessary to document it.
We started writing documentation, but quickly came to the understanding that it was very laborious to prepare it manually. We lose valuable 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 features 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 displayed.
How did you manage to achieve this?
We did not dive deep into the roots of TypeScript - it would take too much time. Using typedoc, we got the project structure in the form of json, according to this structure we mirror the project, but already knowing the descriptions of the components themselves. For convenient loading of descriptions into the documentation itself, we implemented a special component that “pulls” the description from the mirrored structure and displays it on the page. It sounds complicated, but in practice it works like a clock.
Further more. We did not want to copy the code to get an example in the documentation and display the text of the code on which it was written. We made a separate component that displayed both the example and the code for this example. Using a mirrored structure, we were able to achieve a connection between the examples and their source code.
We have posteda solution on the largest GitHub collaborative development 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 entire library to be rebuilt to see the result in the documentation.
- JavaScript support: 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!