search

lunarmodules / ldoc

LDoc is a LuaDoc-compatible documentation generator which can also process C extension source. Markdown may be optionally used to render comments, as well as integrated readme documentation and pretty-printed example files.
https://lunarmodules.github.io/ldoc/
Other
787 stars 173 forks source link

Order for documents and the side bar #108

Closed andrewstarks closed 4 years ago

andrewstarks commented 10 years ago

I have some documents that I want to include. I'd like to have them in a certain order. I find the "01-README" thing to be kind of hackish.

It'd be nice if the order of my topics was respected.

That is:

topics = { "doc_src/introduction.md", "README.md"}

resulted in the introduction coming first.

stevedonovan commented 10 years ago

I think this is an excellent idea, combining this with the convention that if the document has a #title top-level markdown comment, then it should be used as the actual title. Might take a little work, but worth it.

stevedonovan commented 10 years ago

I've decided to switch off module/topic/whatever sorting by default (to restore it 'sort_modules=true`). The reason is exactly that we often have a preferred order, and otherwise grabbing directories will impose order anyway. No doubt this will have ... consequences elsewhere ;)

abadc0de commented 10 years ago

and otherwise grabbing directories will impose order anyway.

For whatever reason, that order seems pretty arbitrary on my system.

screenshot from 2013-11-22 15 48 42

sort_modules=true fixes that nicely, though.

OT: Is there an option to bring back the top-level module in the list on the left, similar to version 1.3 or so (the version in LuaRocks)? For the project shown here, everything in that list on the left was prefixed with moonwalk. in that version, which I liked better -- it's the same name as the module you'd need to require, and the list looks weirdly "skinny" to me without it.

andrewstarks commented 10 years ago

That's downright pretty.

Nice work.

On Fri, Nov 22, 2013 at 2:52 PM, abadc0de notifications@github.com wrote:

and otherwise grabbing directories will impose order anyway.

For whatever reason, that order seems pretty arbitrary on my system.

[image: screenshot from 2013-11-22 15 48 42]https://f.cloud.github.com/assets/3652287/1604135/9ca0e3f8-53b7-11e3-9117-b8e099847cef.png

sort_modules=true fixes that nicely, though.

— Reply to this email directly or view it on GitHubhttps://github.com/stevedonovan/LDoc/issues/108#issuecomment-29108263 .

stevedonovan commented 10 years ago

On Sat, Nov 23, 2013 at 12:07 AM, Andrew Starks notifications@github.comwrote:

That's downright pretty.

Nice work.

Well, that's a nice style sheet! OK, so it seems that sometimes I need to sort modules, and sometimes ... not. Sorting actual modules is fine, but it's the 'topics' we need to leave alone.

Not sorting means that the module order is determined by the input file order - which we can control. If we specify this implicitly with directories then we get the file system ordering, which I think is always sorted with luafilesystem?

abadc0de commented 10 years ago

Heheh, thanks, I got a little carried away with it but I'm pretty happy with it too :)