Docgeni, the Angular component documentation tool out of the box

Link: Docgeni, an out-of-the-box Angular component documentation tool

If there’s one regret for 2020, it’s not making Docgeni open source, even though the code is already public. However, the scaffolding and documentation have not been perfect, and the whole implementation is still rough, so it has not been announced to the public. It has been more than a year since the first line of code was submitted on March 26, 2020. Today, on the good day of 2021-05-20, it officially announced open source and released version 1.0.0.

What is Docgeni?

Docgeni is a documentation tool for Angular component development scenarios that supports component documentation as well as normal Markdown document generation. Docgeni will automatically generate the corresponding document navigation, menu and routing according to the directory structure and FrontMatter, and support the configuration of level 1 navigation and routing to meet the needs of customization; In addition, Docgeni supports importing Example in Markdown syntax for ease of developing components and displaying component examples.

features

📦 allows you to quickly start documentation and component development right out of the box
🏡 Standalone Angular component preview experience, including component overview, samples, and apis
📋 extends the Markdown syntax by importing Example directly into the documentation
💻 multilingual support
🚀 Two modes and multiple styles supported

motivation

So you have to ask: why build another wheel when the community already has a lot of document generation tools? In 2018, we started building our component library with Angular, and after 2-3 years we have 50+ components in our library. So for component library development, documentation and examples is a very important link, we started is like other component library directly in the warehouse to write a Demo site as documentation and examples show, every time a new component will need to add the components in the sample corresponding sample module, sample components, etc., write component sample and document very tedious, In addition, we started building a business component library in 2019, which meant I had to write the same basic sample functions again, and the previous documentation site was very unprofessional, so I started looking for a tool for Angular component development to generate documentation and component samples. The React and Vue frameworks have many solutions, but the Angular framework does not have a component document generation tool out of the box. Familiar Angular component libraries (e.g. Material Design, NG-Zorro-ANTd, NGX-Bootstrap, etc.) were all sample sites built inside the repository that could not be reused directly by other component libraries, so we finally came up with the idea of writing our own documentation tool for Angular component development. Awesome-docgen lists some of the document generation tools we investigated at the time. Storybook is probably the only document generation tool that supports the Angular framework, but its presentation and writing style are too cumbersome to use. I have said this on many occasions: Angular is a great front-end framework, and we’ve always wanted to give back to the community, but Angular doesn’t have an out-of-the-box component library documentation tool. To make the Angular framework ecosystem flourish, we decided to open source Docgeni. Of course, Docgeni is not perfect at present. It only temporarily meets the basic needs of our company, and some advanced features are not supported yet. We will continue to maintain and update and iterate.

Classification of document tools

There are three types of documentation tools:

Common documentation: Documents with pure Markdown syntax, common to both the front and back ends, mainly showing getting started guides, configuration documentation to use, there are countless such tools
Component documentation: basically bound to the front-end framework, showing the usage instructions of components, parameters of components, and Examples of components
API documentation: Like the official Angular API, most component libraries don’t need this feature

Docgeni supports the generation of both plain and component documents, although it is possible to use Docgeni to generate Markdown plain documents for some document-only scenarios.

The characteristics of Docgeni

Here’s a quick look at how Docgeni differs from other component document generation tools.

Preview experience of individual components

For a component, there are overview, examples, and APIS, which are separate and basicMaterial Design ComponentsBe consistent.

Two modes are supported

supportfull 和 liteBoth modes, for some small libraries or pure Markdown documents, may not require header navigation, so Lite mode is most appropriate.

Support for both themes

The default theme header navigation background color is white. If you want the same theme as Angular’s official website, you can set the theme to:angular, the display effect is as follows:

Support for multiple class libraries

If multiple libraries exist in a repository, such as angular/ Components, which contains CDK and components, Then Docgeni can configure multiple library navigation to show different libraries, which is rare.

Strong ability to customize

For document sites, users need to customize Title, Scripts, Styles, Assets, and so on, Docgeni provides publicDir custom index.html, assets,.browserslistrc, styles. SCSS and other functions. For details, see the custom site. If custom public isn’t enough for custom, Docgeni also supports a fully custom site model where users can add custom Angular modules or inject global built-in services under the root module. To fully customize the example site, simply configure siteProjectName: {siteName} and then modify the AppModule code as follows:

import { NgModule } from '@angular/core';
import { RouterModule } from '@angular/router';
import { BrowserModule } from '@angular/platform-browser';
import { DOCGENI_SITE_PROVIDERS, RootComponent } from './content/index';
import { DocgeniTemplateModule } from '@docgeni/template';
@NgModule({
    declarations: [],
    imports: [BrowserModule, DocgeniTemplateModule, RouterModule.forRoot([])],
    providers: [...DOCGENI_SITE_PROVIDERS],
    bootstrap: [RootComponent]
})
export class AppModule {
    constructor() {}
}
Copy the code

The SRC /app/content and SRC /assets folders should be ignored. Instead, create a.gitignore file in the SRC root of your site.

app/content
assets/content
Copy the code

Modify styles. SCSS enter the following:

@import '~@docgeni/template/styles/index.scss';
Copy the code

Quick learning

Execute any of the following commands to initialize the scaffold.

$NPX @docgeni/cli init # or $docgeni init # or $ng add @docgeni/cliCopy the code

@docgeni/cli NPM install -g @docgeni/cli

Using ng add@docgeni /cli requires global Angular cli installation NPM install -g @angular/cli Automatically completes the initial configuration of docgeni after executing any of the above commands. This includes generating configuration files, NPM startup scripts, default documents, and so on.

Step 1 Select document site mode: Full or Lite (default Lite)
Step 2 Enter the document directory (default docs)

After initialization, usenpm run start:docsLaunch the document site, and the browser openshttp://127.0.0.1:4600Can access. The Docgeni initialization scaffolding automatically detects and adds class libraries to the current Angular project. Components of the default class library are not documented or exemplified, so they are not shownAn overview of the components,The documentation calls for writing component documentation and examples, such as: we have a button component at the root of the component, create one under the Button component folderdoc/zh-cn.mdFor the document, enter the following:

-- Title: button -- ## When to use a button to start an immediate operation.Copy the code

The display effect is as follows:Docgeni also provides a template repository:Github.com/docgeni/doc…, you can quickly create an Angular component library with documentation. For more details please refer toQuick learningThe document.

The last

Open source does not mean that Docgeni is mature and stable, only that a minimal version is available. Open source is also a new starting point, and we hope that more Angular users will use it and give feedback to improve it gradually. Here is the known roadmap:

Welcome to follow and contribute. Github.com/docgeni/doc…

A final AD for development teams: Worktile created PingCode, a smarter development management tool that works better than Jira. It’s free for 25 people or less.