What is a documentation generator?
A documentation generator is a tool that programmatically generates technical and software documentation. Most commonly, auto-generated documentation is used for application programming interfaces (APIs), intended for a developer audience. A generator can create documentation from source code and other files, including binaries.
Different documentation generation tools are available for different types of documentation. Some tools are better suited for internal documentation, while others are more useful for external documentation. Likewise, the tool you choose will depend on the expertise required to use your documentation (i.e., if it is highly technical and detailed or high-level).
This is part of a series of articles about documentation tools.
What are the benefits of automating documentation generation?
APIs are a reliable mechanism to connect different applications and provide additional benefits such as rapid deployment, customizability, and cost optimization. APIs with auto-generated documentation can be deployed to end users faster and improve the user experience. They also improve productivity within software development teams tasked with creating and updating the documentation.
For internal documentation, generating docs automatically saves time from the developers who would otherwise write the documents themselves. Automatic generators may also help clarify parts of the codebase that the current developers on the team don’t know well enough to contribute to, let alone to document.
Limitations of documentation generators
Document generators can only deduce information that exists in the code. They can’t deduce business logic, design decisions, let alone the reasons not to implement things in a certain way. In addition, automatic generators don’t always separate the wheat from the chaff, as they may treat all code in the same manner.
Best static analysis documentation generators
These are tools that can generate documentation based on code artifacts. These tools are mainly used for internal developer documentation.
1. Swimm
Swimm is a documentation platform that is transforming the way enterprise engineers discover and generate documentation about code. Utillzing Generative AI combined with years of experience in the documentation and knowledge sharing space, Swimm can generate overview documentation for entire repositories in just a few clicks.
Auto-docs works by using static code analysis combined with relational ranking algorithms to construct a complex, logical understanding of the relationships that exists within your codebase and their relative importance. Auto-docs is language agnostic, including support for languages like Cobol and Assenbly.
Take a look at Auto-docs in action:
Auto-docs gives developers the benefits of great documentation, without the considerable time and resources it would take to write the docs, and then maintain and keep them up to date over time. Auto-docs turns the dreaded thought of creating and maintaining effective documentation into a 1-time automated solution. It’s like the gift that keeps on giving.
In addition to Auto-docs, Swimm has created a number of features that generate documentation for developers as a natural part of the SDLC. Here are a few other ways you can create documentation in the click of a button:
- Snippets2doc generates documentation from selected code snippets
- PR2doc creates a document based on the changes made in a specific pull request
- Branch2doc enables developers to generate a document based on changes made to a particular branch
- Chat2doc utilises answers from /ask (the Swimm AI assistant) to create documentation based on questions and answers
2. Doxygen
Doxygen is a documentation generator tool that can extract documentation from source code and other documentation files and generate it in a structured format, such as HTML, PDF, or LaTeX. Doxygen can extract documentation by using special comments in the source code that tell Doxygen how to interpret the documentation.
It provides a wide range of customization options, including the ability to specify the output format, the level of detail to include in the documentation, and the appearance of the documentation. It integrates well with popular integrated development environments (IDEs) and can be configured through a configuration file or through special comments in the source code.
Best API documentation generator tools
3. SwaggerUI
License: Apache License 2.0
Repository: https://github.com/swagger-api/swagger-ui
Swagger UI lets anyone (whether a developer or end-user) visualize and interact with API resources without accessing the relevant implementation logic. It automatically generates documentation from the OpenAPI specification and provides visuals to facilitate client-side consumption and back-end implementation.
Swagger UI is human-centric, allowing end developers to interact and experiment with all operations exposed by the API—it focuses on usability and readability of the documentation. The tool is fully customizable, providing access to source code to let you modify and style your UI. Finally, there are no dependencies—the UI adapts to any local or web-based development environment.
4. Redoc
License: MIT License
Repository: https://github.com/Redocly/redoc
Redoc is an open source tool for generating API documentation according to the OpenAPI specification. It creates clean, customizable documents in an attractive design with three panels. Markdown support makes it easy to write and style comments.
Redoc uses the OpenAPI specification to generate documents within your browser, so no server is required. Redoc includes a CLI tool for inspecting all Open API definitions based on rules that ensure you adhere to OpenAPI best practices. When you are ready to publish your documentation, there’s only one command to run.
5. DapperDox
License: GNU General Public License v3.0
Repository: https://github.com/DapperDox/dapperdox
DapperDox is an open source, out-of-the-box solution for API documentation. It is a highly flexible tool that allows you to design pages according to your needs. Like Redoc, DapperDox supports Markdown.
DapperDox has a clean, two-column user interface—the first column contains the navigator and the second column contains the details of the API methods. You can also customize page themes ( a feature not provided by Redoc).
With DapperDox, you can write complete documentation using GitHub Flavored Markdown. You can document many API specifications as a set of products with cross-referencing. It also lets you place your content seamlessly into automatically generated references.
The tool integrates a built-in API browser with your authentication systems and APIs. It can proxy the development platform to enable fully integrated API key management. You can choose from several themes or create a new one.
6. RapiDoc
License: MIT License
Repository: https://github.com/rapi-doc/RapiDoc
RapiDoc is an interactive API documentation tool that lets you create visually appealing documents using the OpenAPI specification. It is flexible, enabling the customization of themes, fonts, and colors. You can embed your documentation into HTML code or embed external code into your documentation.
RapiDoc includes an easy-to-use, out-of-the-box console for making API calls and testing APIs. You can use JavaScript to modify its attributes, just like with HTML. Similar to SwaggerUI, a single-column view and collapsible bars contain the console and JSON payloads.
Learn more in our detailed guide to best documentation tools (coming soon).
