A tool for creating a simple and fast documentation ?

Questions about the LÖVE API, installing LÖVE and other support related questions go here.
Forum rules
Before you make a thread asking for help, read this.
Post Reply
User avatar
Linkpy
Party member
Posts: 102
Joined: Fri Aug 29, 2014 6:05 pm
Location: France
Contact:

A tool for creating a simple and fast documentation ?

Post by Linkpy » Fri Oct 07, 2016 11:52 am

Hello !

I'm creating a game, but I do the "framework" before the game it-self. And I search for a documentation tool with a clean visual and search tool included (and not only a "website"-generator).

Do you know a software than generate or use a formatted file (XML, JSON, etc) for creating a documentation or just for displaying it ?
I known a software which done this though XML files but totally forgot the name of it.

Thanks for your help !
Founder of NeoShadow Studio. Currently working on the project "Sirami".
github / linkpy

User avatar
kikito
Inner party member
Posts: 3153
Joined: Sat Oct 03, 2009 5:22 pm
Location: Madrid, Spain
Contact:

Re: A tool for creating a simple and fast documentation ?

Post by kikito » Fri Oct 07, 2016 12:54 pm

As far as I know, "simple" and "with a search tool (not only a website)" are opposites.

You could use LDoc. That's a "website-like" tool. But it is simple.

I also like locco, but again that is a "website-like" tool.
When I write def I mean function.

User avatar
Linkpy
Party member
Posts: 102
Joined: Fri Aug 29, 2014 6:05 pm
Location: France
Contact:

Re: A tool for creating a simple and fast documentation ?

Post by Linkpy » Fri Oct 07, 2016 2:12 pm

kikito wrote:As far as I know, "simple" and "with a search tool (not only a website)" are opposites.
By "simple", I mean something simple to setup and configure.

LDoc and Locco is suitable but I want something more simple. Something like Dash / Zealdocs but using a simple file format. I want to write all the documentation by my-self without any generation steps.
Founder of NeoShadow Studio. Currently working on the project "Sirami".
github / linkpy

User avatar
airstruck
Party member
Posts: 650
Joined: Thu Jun 04, 2015 7:11 pm
Location: Not being time thief.

Re: A tool for creating a simple and fast documentation ?

Post by airstruck » Fri Oct 07, 2016 4:58 pm

Linkpy wrote:I want to write all the documentation by my-self without any generation steps.
Bottom line is unless you're writing it in exactly the format your front-end (Dash/Zeal) needs, you're going to have a generation step. And even if you write the DDL and all the inserts for the search database by hand, you have to actually run it to create the database. I don't know if you consider that a generation step or not, but it seems like one to me.

If no generation steps is really important to you, your options are limited. You can write the docs in plain text; there's no generation steps there. You could write them in markdown and parse it on the fly when it's viewed (is that a generation step?), or you could write it in HTML, or some other display format like LaTeX.

Why not go with the usual docblocks -> generator -> output approach?

User avatar
Linkpy
Party member
Posts: 102
Joined: Fri Aug 29, 2014 6:05 pm
Location: France
Contact:

Re: A tool for creating a simple and fast documentation ?

Post by Linkpy » Fri Oct 07, 2016 8:17 pm

But generation steps I meant generating the documentation from the source. The only "generation" step I want is taking my documentation files and create a usable output files.

I'm trying MkDocs right now, and it is quiet good.

And, for having a clean source code, I don't want to have dozen of lines of doc in my files, but having a well and deep documentation elsewhere.
Last edited by Linkpy on Sat Oct 08, 2016 7:05 am, edited 1 time in total.
Founder of NeoShadow Studio. Currently working on the project "Sirami".
github / linkpy

User avatar
airstruck
Party member
Posts: 650
Joined: Thu Jun 04, 2015 7:11 pm
Location: Not being time thief.

Re: A tool for creating a simple and fast documentation ?

Post by airstruck » Fri Oct 07, 2016 8:29 pm

Got you. MkDocs looks pretty nice, good find. Markdown seems like a good option if you don't want docs in the source.

Some doc generators just read docs and don't care about source, so that could be another option if you want better special handling for API docs. You could just have one file that's a big docblock with mostly markdown and some doc tags (@function, @param and so on).

Post Reply

Who is online

Users browsing this forum: Google [Bot], pgimeno and 52 guests