Re: [textadept] How to generate documentation like TA's?

From: HyperHacker <hyperhac....at.gmail.com>
Date: Tue, 28 Feb 2012 06:44:06 -0700

On Tue, Feb 28, 2012 at 06:39, mitchell <c....at.caladbolg.net> wrote:
> Hi,
>
>
> On Mon, 27 Feb 2012, HyperHacker wrote:
>
>> On Sun, Feb 26, 2012 at 08:47, mitchell <c....at.caladbolg.net> wrote:
>>>
>>> Hi,
>>>
>>> On Fri, 24 Feb 2012, HyperHacker wrote:
>>>
>>>> On Fri, Feb 24, 2012 at 07:03, mitchell <c....at.caladbolg.net> wrote:
>>>>>
>>>>>
>>>>> Hi,
>>>>>
>>>>> [snip]
>>>>>
>>>>>
>>>>> How are you creating your luadoc and adeptsense files? Using
>>>>> ./update_doc?
>>>>> If so, you must be putting your sources within ta's _HOME and that
>>>>> should
>>>>> pick up the '-- Markdown:' comments in your code...
>>>>>
>>>>> mitchell
>>>>>
>>>>
>>>> OK, my sources are in another directory, so I made a symlink to that
>>>> directory within TA's home. It looks like it's finding those, but
>>>> expecting something else first:
>>>> /usr/bin/lua: ./update_doc:63: ../doc/modules/rena.log.html: No such
>>>> file or directory
>>>> (I had to patch update_doc, line 63, to generate a meaningful error
>>>> message: )
>>>> - f = io.open(filename)
>>>> + f = assert(io.open(filename))
>>>
>>>
>>>
>>> This means LuaDoc did not pick up a module called 'rena.log' (hence why
>>> its
>>> html file does not exit). Ensure that your module would be passed to
>>> LuaDoc
>>> for processing on line 27 (the second os.execute).
>>>
>>>
>>>> Before that I had just been doing:
>>>> luadoc -d doc -doclet adeptsensedoc *.lua
>>>> in the source directory to generate the tags, and then loading them
>>>> with .textadept/modules/lua/post_init.lua:
>>>> _M.lua.sense:load_ctags('/home/rena/dev/lua/libs/rena/doc/tags')
>>>> table.insert(_M.lua.sense.api_files,
>>>> '/home/rena/dev/lua/libs/rena/doc/api')
>>>>
>>>> which works except for the missing markdown.
>>>
>>>
>>>
>>> As you are now aware, adeptsensedoc only generates Adeptsense from
>>> LuaDoc.
>>> It doesn't know anything about '-- Markdown:'. The 'if luadoc' block in
>>> update_doc is what inserts markdown into the LuaDoc html files.
>>>
>>> I hope this helps,
>>>
>>> mitchell
>>>
>>
>> Ah, does this mean I have to copy/link every html file from my
>> documentation into that directory? I was hoping to get away with just
>> a symlink to the directory it's in...
>
>
> I know you solved this further down, but I think this thread indicates some
> changes should be made to make it easier to document custom modules via '--
> Markdown:'. I will be looking into this.
>
>
> mitchell
>
> --
> You received this message because you are subscribed to the Google Groups
> "textadept" group.
> To post to this group, send email to textadept.at.googlegroups.com.
> To unsubscribe from this group, send email to
> textadept+unsubscribe.at.googlegroups.com.
> For more options, visit this group at
> http://groups.google.com/group/textadept?hl=en.
>

mm, I can think of quite a few improvements I'd like to make to
LuaDoc. I'll probably have a go at implementing them via taglets at
some point. Some things that come to mind are:
-Support for optional parameters: @param [foo=42] description of foo
-Support for @note and @warning to add notes to a function description
-Support for @abstract and something like @usage/@example for module
descriptions
-Support for @deprecated to note a module/function as being deprecated
(indicated by a note in its description and maybe different
formatting)

Although this is a bit off topic...

-- 
Sent from my toaster.
Received on Tue 28 Feb 2012 - 08:44:06 EST

This archive was generated by hypermail 2.2.0 : Thu 08 Mar 2012 - 12:32:30 EST