Looking for open source documentation generator

#1

Post by withshubh » Thu, Mar 28, 2024, 11:54 AM UTC

I have worked with docusauras and I believe that initially, it requires too much developer effort to make it look beautiful or customise.

Got to know about Docus.dev and Nextra.site but didn't find any examples that have API docs (using OpenAPI specs)

Re: Looking for open source documentation generator

#2

Post by warrenm » Thu, Mar 28, 2024, 1:07 PM UTC

First problem ... define what you mean by "documentation"

We talking javadocs? MSDN? IBM developerWorks? Docs.Splunk? ReadTheDocs.io? GitHub readme.md? ...?

Re: Looking for open source documentation generator

#3

Post by mikewarot » Thu, Mar 28, 2024, 6:19 PM UTC

Good documentation can't be automated. It requires someone to carefully craft working examples of all the parameters and functions that are available, so you can copy/paste them into a program to try them out.

I'd expect at least two separate people are required... a writer and an editor.

Re: Looking for open source documentation generator

#4

Post by withshubh » Thu, Mar 28, 2024, 6:58 PM UTC

mikewarot wrote: post #3

Good documentation can't be automated. It requires someone to carefully craft working examples of all the parameters and functions that are available, so you can copy/paste them into a program to try them out. I'd expect at least two separate people are required... a writer and an editor.

It's not about automating the documentation. It is about the static site generators for documentation. Ex: https://docusaurus.io/

Re: Looking for open source documentation generator

#5

Post by withshubh » Thu, Mar 28, 2024, 6:59 PM UTC

warrenm wrote: post #2

First problem ... define what you mean by "documentation" We talking javadocs? MSDN? IBM developerWorks? Docs.Splunk? ReadTheDocs.io? GitHub readme.md? ...?

Did you check the websites I mentioned in the description?

Re: Looking for open source documentation generator

#6

Post by flexwie » Sat, Mar 30, 2024, 4:13 PM UTC

Astro has tools to build documentation from OpenAPI specs. Found it a bit easier to get started with customization compared to docusaurus.

Re: Looking for open source documentation generator

#7

Post by warrenm » Sat, Mar 30, 2024, 10:40 PM UTC

withshubh wrote: post #5

warrenm wrote: post #2

First problem ... define what you mean by "documentation" We talking javadocs? MSDN? IBM developerWorks? Docs.Splunk? ReadTheDocs.io? GitHub readme.md? ...?

Did you check the websites I mentioned in the description?

Yes - but that's still not automating the documentation ... it's only [potentially] automating presenting it

So ... back to my initial narrowing-down inquiry :)