- Let’s talk JS ⚡: Documentation
- By Arek Nawo
- The Nuggets translation Project
- Permanent link to this article: github.com/xitu/gold-m…
- Translator: Starrier
- Proofreader: Wznonstop, SHERlocked93
If you’ve ever worked on an open source project, or one large enough to require documentation, then you know how important it is to write qualified documentation. In addition, documentation needs to always be up to date and should include all public apis. So how do you make the perfect document? The goal of this article is to use JS style to solve this problem! ⚡
Photo by rawpixel / Unsplash
And there are only two ways…
There are only two ways to document your project. That is, write it yourself or generate it automatically. There’s no dark magic here, and there’s no other way.
So, let’s start with “write your own document.” In this scenario, you can easily create beautiful documentation sites. Of course, this will require more work on your part, but if you think it’s worth it, go for it. 👍 Of course, you need to consider keeping your documents in real time, which can cause additional time costs. Customisability is the biggest advantage. Your documentation will probably be written using Markdown (the most common GFM) — it’s just a standard. You can make it look pretty, which is important if you are creating OSS. There are libraries that can help you with this task, and we’ll take a closer look at them later.
Next, we can choose to generate documentation from the code itself. Obviously, it’s not that straightforward either. First, you must use a tool like JSDoc to write documentation in the form of Javadoc-like comments. So, it’s not like you can just generate documentation. JSDoc is pretty good now. I mean, look at its official documentation and see how many tags you can use. In addition, modern code editors will grab your type definitions and other descriptions to help you use auto-complete and popup documents during development. When you write a simple markdown, you won’t achieve this effect. Of course, you’ll need to write separate files like the README, and the generated documents will be a bit programmatic, but I don’t think that’s a big deal.
Choosing the right tool…
So let’s say you’ve decided to create documents manually (or should I say with a keyboard) and use Markdown (or maybe you just learned about MarkDown from somewhere else). Now, you’ll probably need a tool called Renderer, which will turn your MD (Markdown) into a nice mix of HTML, CSS, etc. This is if you don’t just want to post it to GitHub, or GitHub wikis. Or you want MD to attach an extra reader (like this). Now, in order to solve this task (IMHO), I will list some of the best tools for you. 😉
Docsify
Docsify login screen
Docsify is an amazing document site generator. It does the job of document generation very well. Importantly, it renders your documents dynamically, which means you don’t have to parse MD to HTML — just put your files in the right place! In addition, Docsify has a large number of plug-ins and themes to choose from. It is also well documented (like the document generator). I might be a little biased when using this tool for my own project documentation. The only problem with it (at least to me) is that compatibility with IE 10 (as it says on the home page) is not very good (but they are trying) and it lacks the necessary support for related links.
Docute
Docute v4 document
Docute is a tool similar to Docsify, but with a cute name. The latest version (V4) has less documentation than the previous version and is somewhat simplified. The resulting document looks simple and elegant. Themes can be customized using CSS variables. Docute doesn’t have as powerful a plug-in system as Docsify, but it has its advantages. It is built on vue.js, which results in a larger package size than Docsify, but much more extensible. For example, in your MD file, you can use some of the built-in Vue components, or even your own.
Slate
Slate document
Slate is probably the leader in keeping track of your projects and the number of tiny stars on GitHub (~25,000). Its documentation is clear, its syntax is readable, and it has everything-on-one-page features. It also has a very reliable GH Wiki documentation. It allows for deep themetization, but because the documentation doesn’t provide much information, you’ll need to do your own source mining. Unfortunately, its scalability is poor, but it is so feature-rich that it seems like a good choice for those who need REST API documentation. Remember, Slate generates static HTML files, not dynamically at run time
Docusaurus login screen
Docusaurus
Docusaurus is an easy tool to maintain open source document generation sites. It was created by Facebook using — yes, it’s React. It makes it easy to transform or integrate React components and libraries into a whole to create custom pages. It also allows you to create additional blogs and integrate them directly into your documentation site without any other tools! It integrates well with Algolia DocSearch to make your documents easy to navigate. Just like Slate, it generates static HTML files.
VuePress login page
VuePress
VuePress is a VUUe-powered static site generator developed by the founders of vue.js. It is also a reliable tool for generating official vue.js documentation. As a generator, it has very friendly documentation. It also has a powerful plugin and theme system, and of course inherits excellent vue.js. UePress claims to be SEO friendly because it generates and outputs HTML files.
GitBook login page
GitBook
GitBook is a tool for writing MD documents and text. It gives you an online editor and a free.gitbook. IO domain experience. There’s no doubt that an online editor is great, but when it comes to layout, it’s not very customizable. There is also a legacy desktop version of the editor. But unless you’re working on an open source project, you’ll have to pay for it.
The generator!
Now that we’ve covered the best documentation tools, let’s start with generators, shall we? Generators primarily allow you to create documentation from annotated code.
JSDoc login page
JSDoc
JSDoc is probably the most obvious and well-known document generator for JS. It supports a wide variety of tabs and is friendly to almost all editors and IDE autocomplete features. Its output can be customized using a variety of themes. And there are so many different kinds of topics. More interestingly, with this and other generators, you can output markdown for later use with any of the documentation tools listed above.
TypeDoc login page
TypeDoc
TypeDoc can be thought of as TypeScript JSDoc. The main reason it makes the list is that there are few (or no) document generators that support the TS type. With this tool, you can generate documents based on the TypeScript type system, including structures such as interfaces and enumerations. Unfortunately, it only supports a small number of JSDoc tags, and there is no large community like JSDoc. As a result, it doesn’t have many topics and is poorly documented. IMO’s best way to use this tool effectively is to use the Markdown theme plug-in and use one of the documentation tools.
ESDoc login page
ESDoc
ESDoc is similar to JSDoc in function. It supports comment tags similar to JSDoc. It provides optional support for document code style testing or coverage testing. It has a large collection of plug-ins. There are also proof-of-concept plug-ins for TypeScript, Flow, and Markdown output.
Documentation.js
Documentation. Js is a modern document generator that can output HTML, JSON, or markdown with great flexibility. It supports ES 2017, JSX, Vue templates, and Flow types. It can also do type inference and native – JSDoc markup. It has deep topic options based on the underscore template. Unfortunately (for me), it doesn’t support TypScript. 😕
DocumentJS login interface
DocumentJS
DocumentJS is a document generation solution that is not as popular as its competitors above. Support for most JSDoc and Google closure compiler tags, plus the ability to add custom add-ons. It only generates themeable HTML by default, but is highly extensible.
Different content…
I’ve listed some standard documentation tools and generators above. Of course, they can be used together to create good documentation. But I’d like to recommend one more tool for you. Have you heard of literate Programming? That is, you can use markdown syntax to write comments and generate code from it. It literally turns your code into poetry.
Docco login page
You then use a tool like Docco to convert your MarkDown commented code into markdown with code snippets. I can say it’s something new. 😁
You already know 😉
I hope this article has at least made creating your documentation a little easier. The above list contains projects that are top quality and well maintained (so far). If you liked this article, please consider sharing it, you can follow me on Twitter, or subscribe to the mailing list below for more great articles. 🦄
If you find any mistakes in your translation or other areas that need to be improved, you are welcome to the Nuggets Translation Program to revise and PR your translation, and you can also get the corresponding reward points. The permanent link to this article at the beginning of this article is the MarkDown link to this article on GitHub.
The Nuggets Translation Project is a community that translates quality Internet technical articles from English sharing articles on nuggets. The content covers Android, iOS, front-end, back-end, blockchain, products, design, artificial intelligence and other fields. If you want to see more high-quality translation, please continue to pay attention to the Translation plan of Digging Gold, the official Weibo, Zhihu column.