API Documentation Tool

Solar2D General Questions/Discussion
#1

(I feel like I asked this before, but I can’t find the post now.)

What tool does Corona use to create the API documentation? It looks so much nicer than other API doc tools I’ve found. Perhaps it’s using one of these others (luadoc?), but just styled much, much better?

I need to document a web api (C#) I’ve created that several folks now want to use. We just have a Google Doc at the moment, and it’s just not sufficient.

I’d also like to use it to document some of the specialized Lua objects we’ve created. Lately I’ve been creating an \examples subfolder in our project, and just sticking some code snippets in there about how to use them, which properties/methods are available, etc.

Thanks,

Dave

#2

Oh, I forgot to add that I’m not looking for a tool to *automatically* generate documentation.  I don’t mind writing it out, along with appropriate code samples. I just want the format to be very clear.

Dave

#3

Hi Dave,

You should check out Corona Labs’ “Template for Library Documentation” on GitHub - I think it might give you what you’re looking for. Here’s a link: http://github.com/coronalabs/plugins-template-library-docs

#4

Yeah, that does help. Thanks! I suppose I could just put the docs directly into GitHub… 

(By the way, there’s an extra space at the end of that URL that makes it not work when it’s clicked. Removing it works fine.) 

But I’m still interested in the workflow and tools used. I’m guessing that Corona does something like this:

  1. Write the documentation in Markdown syntax. (What editing tool is used?)

  2. Use pandoc to convert it to HTML for the website. (Is this automated somehow?)

I’ve tried several Markdown editors today, and so far they have all fallen short for different reasons. And so far, none of what I’ve tried has supported color coding lua code in their Previews the way Corona’s docs do, although VS Code got closest.

I’ve tried:

  • Atom Editor with Markdown Preview - good, except no Lua color coding.
  • VS Code - good, except Markdown Preview theme matches color scheme of app (which in my case is black); tried changing to a custom style.css, as shown in VS Code documentation, and I can’t get the styles to look correct. I just want it exactly like Corona or Github. I even tried, as a test, to point to the corona api docs stylesheet, but it also didn’t look correct.
  • Lua Glider doesn’t seem to have any Markdown support that I could find.
  • ZeroBrane Studio has limited Markdown support (in comments); not what I’m looking for in this case.
  • MacDown for OS X looks great, but no lua color coding.

Thanks,

Dave

#5

I also wonder, if creating documentation using markdown syntax like this… How does Corona do the breadcrumbs?

ie. https://docs.coronalabs.com/api/library/audio/dispose.html

Breadcrumbs show: Docs > API > Libraries > audio > dispose

I would think the breadcrumbs are auto generated, but how?

Dave

#6

@Jason,

Tip: Posting GitHub links with HTTPS in the forums often fails to work.  Folks who are thinking simply cut-copy-paste the link minus the HTTPS, but many stop after clicking the link and seeing an error. i.e. While it is easy to solve, lots of forums users get stuck when the link doesn’t seem to work.

I have found that simply pasting the link, and changing the URL prefix to http solves this problem:

http://github.com/coronalabs/plugins-template-library-docs

(and of course it fails … ha ha… debugging now)

(ah, of course… pasted in unnecessary whitespace in the link…fixed now)

#7

Thanks, Ed! Updated the link in my original post. 

#8

We use pandoc with a bunch of wrapper scripts to build the breadcrums and a few other things.  Most of the people in the office use what ever their normal IDE is to edit the md text. Simple changes are some times done via the repo web interface.

#9

I wish you could make some of your scripts available to build the api docs. :slight_smile:  I’ve never actually used pandoc, so I’m not familiar with how it works other than what I learned from looking at the site briefly earlier.

How do you integrate pandoc into the workflow though? Is it on a schedule? Or does it run every time someone checks in a .md file? Or is it just manually executed whenever you feel like updating the documentation?

Thanks,

Dave

#10

All of that stuff is run via jenkins. Release documentation is updated when ever there is a checkin, daily build docs are built as part of the build process and uploaded with the installers.

#11

Oh, I forgot to add that I’m not looking for a tool to *automatically* generate documentation.  I don’t mind writing it out, along with appropriate code samples. I just want the format to be very clear.

Dave

#12

Hi Dave,

You should check out Corona Labs’ “Template for Library Documentation” on GitHub - I think it might give you what you’re looking for. Here’s a link: http://github.com/coronalabs/plugins-template-library-docs

#13

Yeah, that does help. Thanks! I suppose I could just put the docs directly into GitHub… 

(By the way, there’s an extra space at the end of that URL that makes it not work when it’s clicked. Removing it works fine.) 

But I’m still interested in the workflow and tools used. I’m guessing that Corona does something like this:

  1. Write the documentation in Markdown syntax. (What editing tool is used?)

  2. Use pandoc to convert it to HTML for the website. (Is this automated somehow?)

I’ve tried several Markdown editors today, and so far they have all fallen short for different reasons. And so far, none of what I’ve tried has supported color coding lua code in their Previews the way Corona’s docs do, although VS Code got closest.

I’ve tried:

  • Atom Editor with Markdown Preview - good, except no Lua color coding.
  • VS Code - good, except Markdown Preview theme matches color scheme of app (which in my case is black); tried changing to a custom style.css, as shown in VS Code documentation, and I can’t get the styles to look correct. I just want it exactly like Corona or Github. I even tried, as a test, to point to the corona api docs stylesheet, but it also didn’t look correct.
  • Lua Glider doesn’t seem to have any Markdown support that I could find.
  • ZeroBrane Studio has limited Markdown support (in comments); not what I’m looking for in this case.
  • MacDown for OS X looks great, but no lua color coding.

Thanks,

Dave

#14

I also wonder, if creating documentation using markdown syntax like this… How does Corona do the breadcrumbs?

ie. https://docs.coronalabs.com/api/library/audio/dispose.html

Breadcrumbs show: Docs > API > Libraries > audio > dispose

I would think the breadcrumbs are auto generated, but how?

Dave

#15

@Jason,

Tip: Posting GitHub links with HTTPS in the forums often fails to work.  Folks who are thinking simply cut-copy-paste the link minus the HTTPS, but many stop after clicking the link and seeing an error. i.e. While it is easy to solve, lots of forums users get stuck when the link doesn’t seem to work.

I have found that simply pasting the link, and changing the URL prefix to http solves this problem:

http://github.com/coronalabs/plugins-template-library-docs

(and of course it fails … ha ha… debugging now)

(ah, of course… pasted in unnecessary whitespace in the link…fixed now)

#16

Thanks, Ed! Updated the link in my original post. 

#17

We use pandoc with a bunch of wrapper scripts to build the breadcrums and a few other things.  Most of the people in the office use what ever their normal IDE is to edit the md text. Simple changes are some times done via the repo web interface.

#18

I wish you could make some of your scripts available to build the api docs. :slight_smile:  I’ve never actually used pandoc, so I’m not familiar with how it works other than what I learned from looking at the site briefly earlier.

How do you integrate pandoc into the workflow though? Is it on a schedule? Or does it run every time someone checks in a .md file? Or is it just manually executed whenever you feel like updating the documentation?

Thanks,

Dave

#19

All of that stuff is run via jenkins. Release documentation is updated when ever there is a checkin, daily build docs are built as part of the build process and uploaded with the installers.