Online documentation generator for Node.JS projects
Documentation is one of the most important parts of any project, especially if it is an open source project that other people will read. To make the world opensource a little bit better, I tried to gather my knowledge in the field of organizing nodejs modules for projects and make a tool like Makedoc! . Remark for ruby ​​followers: this is almost the same as rdoc.info for Ruby.
This tool analyzes the project code, highlights potentially documented pieces of code (not important, with or without documentation), and generates a static set of pages describing the project.
In a nutshell, the usage pattern is as follows: go to jsdoc.info/[githubusername[/[projectname] and see the finished project documentation. Or go to jsdoc.info/[githubusername] and get a list of projects for which you can generate documentation.
')
For implementation details, please under the cat.
For starters, here's what it looks like:
jsdoc.info/visionmedia/express
jsdoc.info/jaredhanson/passport
jsdoc.info/1602/express-on-railway
jsdoc.info/1602/jugglingdb
The makedoc module is responsible for analyzing the code. This module can be used as a separate tool if your project is not hosted on the github in open access. Makedoc parses the files in search of three basic semantic units: class methods, instance methods, and just methods. Also, each file is defined either as a class file (contains a class description), or as a module file (contains export functions).
The recommended format for documentation is jsdoc. However, he does not understand strictly. Full support will be as the project develops. So, if you can find the documentation for the method, it is parsed with the help of markdown, and the method is marked as “documented”. As a result, we have such a metric as “Docs coverage” - the ratio of the number of lines covered by documentation to the number of undocumented lines. The last digit is taken not the total number of lines of the project, but only the lines in the methods, so that the figure of 100% is achievable.
The project runs on a 100mb RAM host, with a narrow channel and a small disk, so that everything works quickly, the project is not cloned to the hard disk, only the necessary files are downloaded, html is parsed using jsdom + jquery. Initially, there was a version with a repository cloning, which worked much slower and no better. Therefore, we restrict ourselves to the source code in the ./lib directory and not further than the second level of nesting (covers 90% of verified projects).
RailwayJS handles “missing” static middleware requests and sends generated documentation. Further requests are given statics.
The project is a week old, so for now the absolute minimum has been implemented which can be shown. Plans to develop and improve the parser to support as many projects as possible. Next priority: automating the generation process. Already, you can send a POST request to / user / repo / update and update the documentation using a POST-receive hook on github. But who will set it up? It should be like in travis-ci: one toggle switch and ready.
While the generation requests are spaced out in time, everything works without complaints, because the static is given quickly, and the analysis does not require large resources. However, if the project “flies” and is claimed, more serious hardware will be required. Therefore, I ask you to relate loyally to the possible habr effect.
At the moment, feedback from project owners interested in using the resource is very necessary. It’s best to choose the direction of development of a community-oriented project together with active participants in this community, whom I want to find in Habré.
PS: for the problems found on the site we create issues here: github.com/1602/railway-jsdoc-generator/issues
about problems with the generator of documentation we write here: github.com/1602/makedoc/issues
This tool analyzes the project code, highlights potentially documented pieces of code (not important, with or without documentation), and generates a static set of pages describing the project.
In a nutshell, the usage pattern is as follows: go to jsdoc.info/[githubusername[/[projectname] and see the finished project documentation. Or go to jsdoc.info/[githubusername] and get a list of projects for which you can generate documentation.
')
For implementation details, please under the cat.
For starters, here's what it looks like:
jsdoc.info/visionmedia/express
jsdoc.info/jaredhanson/passport
jsdoc.info/1602/express-on-railway
jsdoc.info/1602/jugglingdb
How it works
Macadoc
The makedoc module is responsible for analyzing the code. This module can be used as a separate tool if your project is not hosted on the github in open access. Makedoc parses the files in search of three basic semantic units: class methods, instance methods, and just methods. Also, each file is defined either as a class file (contains a class description), or as a module file (contains export functions).
Jsdoc
The recommended format for documentation is jsdoc. However, he does not understand strictly. Full support will be as the project develops. So, if you can find the documentation for the method, it is parsed with the help of markdown, and the method is marked as “documented”. As a result, we have such a metric as “Docs coverage” - the ratio of the number of lines covered by documentation to the number of undocumented lines. The last digit is taken not the total number of lines of the project, but only the lines in the methods, so that the figure of 100% is achievable.
Tech stack: nodejs, railwayjs, bootstrap, jsdom, jquery
The project runs on a 100mb RAM host, with a narrow channel and a small disk, so that everything works quickly, the project is not cloned to the hard disk, only the necessary files are downloaded, html is parsed using jsdom + jquery. Initially, there was a version with a repository cloning, which worked much slower and no better. Therefore, we restrict ourselves to the source code in the ./lib directory and not further than the second level of nesting (covers 90% of verified projects).
RailwayJS handles “missing” static middleware requests and sends generated documentation. Further requests are given statics.
Plans
The project is a week old, so for now the absolute minimum has been implemented which can be shown. Plans to develop and improve the parser to support as many projects as possible. Next priority: automating the generation process. Already, you can send a POST request to / user / repo / update and update the documentation using a POST-receive hook on github. But who will set it up? It should be like in travis-ci: one toggle switch and ready.
While the generation requests are spaced out in time, everything works without complaints, because the static is given quickly, and the analysis does not require large resources. However, if the project “flies” and is claimed, more serious hardware will be required. Therefore, I ask you to relate loyally to the possible habr effect.
At the moment, feedback from project owners interested in using the resource is very necessary. It’s best to choose the direction of development of a community-oriented project together with active participants in this community, whom I want to find in Habré.
Thank!
PS: for the problems found on the site we create issues here: github.com/1602/railway-jsdoc-generator/issues
about problems with the generator of documentation we write here: github.com/1602/makedoc/issues
Source: https://habr.com/ru/post/141334/
All Articles