DEV Community

Cover image for A short-list with documentation generators in 2019
Sm0ke
Sm0ke

Posted on • Updated on

A short-list with documentation generators in 2019

Hello Coders,

At some point, in order to improve our skills, we read the documentation provided by the underline technology. In this article, I am trying to curate a list of the best tools used to generate docs, in 2019, starting with the ones used by me in various projects, in the last 3/4 years.

Because I'm not a documentation tools guru and the list will be a short one, feel free to add your preferred documentation tool and explain why you are choosing it over others.

Thanks for reading! - Content provided by App Generator.


Here is my list:

  • Gitbook - live sample
  • MkDocs - a really nice tool
  • Sphinx - written in Python, with native search (no Algolia dependency)
  • Gatsby Antd Docs - a GatsbyJS based documentation generator, require Algolia plugin for search
  • Docusaurus looks promising, the major drawback was the ugliness of the default theme.
  • Vuepress - Vue.js based tool.
  • KB4IT - KB4IT is a static website generator based on Asciidoctor - demo

The list will be updated with the tools mentioned in the comments


Thanks for reading! For more resources, feel free to access:

Discussion (12)

Collapse
evanoman profile image
Evan Oman

I am a huuge fan of AsciiDoc. The syntax is very similar to MarkDown, making the source easily readable. However it has a lot of extra features for rendering and composing source files so can be used to build all sorts of documents. You can render the same source into HTML, PDF, DocBook, and even a man-page format. Plus the tooling is available on CLI and in our Java Gradle projects using AsciiDoctorJ.

Collapse
sm0ke profile image
Sm0ke Author

The post-processing translation to PDF, EPUB ... can be very useful.
I will add it to the list.
Also, feel free to share a documentation project, in the case is public.

Collapse
pingvin235 profile image
Shamil Vakhitov

AsciiDoctor is cool, here is an extended and more production ready generator on top of AsciiDoctorJ: pzdcdoc.org

Collapse
cjbrooks12 profile image
Casey Brooks

I've been building Orchid to be especially good for making a single website for both wiki-type prose documentation, and also API docs for your code. It also deploys your site automatically to Github Pages!

GitHub logo orchidhq / Orchid

Build and deploy beautiful documentation sites that grow with you

Orchid

Linux and Mac Build Status Windows Build status Current Version License: LGPL-3.0 Codacy Grade Codacy Coverage Gitter chat Backers on Open Collective Sponsors on Open Collective Open Source Helpers

A beautiful and truly unique documentation engine and static site generator.

Example Orchid site

Orchid is a brand-new, general-purpose static site generator for Java and Kotlin, with a focus on extensibility and aimed at developers looking to improve their technical documentation. Orchid was born out of a desire for better-looking Javadocs and frustration with how difficult is it to manage large Jekyll sites and keep it up-to-date with your code.

Orchid supports a variety of plugins, including a wiki, static pages, blogs, and much more. It aims to have high compatibility with many of the existing static site generators, such as Jekyll, Gitbook, and Hugo, so that migration to Orchid is painless. And if you can't find a plugin to do what you need, Orchid provides an intuitive way to add your own private plugins and a rich API so you can make your site as beautiful and unique as an Orchid.

It currently supports generating docs for Java, Kotlin, Groovy, and Swift; Ruby and Javascript are on the roadmap too. A recent update also added support for automatically pulling in wiki content from Github and Gitlab Wikis.

Here's a good intro to getting started with Orchid:

Collapse
sm0ke profile image
Sm0ke Author

looks good.

Collapse
t00m profile image
Tomás Vírseda

Hi there!

Not sure if my application falls in this category but I have just released a project in GitHub with the same purpose: generate a website based on Asciidoctor sources.

I wrote a post here some days ago.

Thanks for the list!

Collapse
sm0ke profile image
Sm0ke Author • Edited on

Hello Tomas,
I will take a look. Thank You!

[Update] - KB4IT added to the list along with a Github *
Good luck with the project.

Collapse
alexanderalemayhu profile image
Alexander Alemayhu • Edited on

VuePress is really nice and give you a good look by default, IMHO a three word summary is not really fair. Since it has a lot to offer like themes, configuration and plugins. Also the PWA things are neat.

Collapse
arrlancore profile image
arrlancores

Previously I choose docsify to create our dev guideline, it really easy to use and all javascript dev can use it with only need to install the package via npm.

Collapse
sm0ke profile image
Sm0ke Author

Hello,
I've added docsify to the list. In case you have a public project somewhere built with Doscsify, please share it.

Collapse
berislavlopac profile image
Berislav Lopac

I particularly like mkdocs.org/

Collapse
sm0ke profile image
Sm0ke Author

Yep, this tool does the job.