bootDoc - advanced DDoc framework using Twitter's Bootstrap

[Ary Manzana]

On 5/3/12 1:23 PM, Jakob Ovrum wrote:
> On Thursday, 3 May 2012 at 05:44:47 UTC, Ary Manzana wrote:
>> On 5/3/12 1:26 AM, Jakob Ovrum wrote:
>>> This project is finally published and documented, so here's an
>>> announcement.
>>>
>>> https://github.com/JakobOvrum/bootDoc
>>>
>>> bootDoc is a configurable DDoc theme, with advanced JavaScript features
>>> like a package tree and module tree, as well as fully qualified symbol
>>> anchors. The style itself and some of the components come from Twitter's
>>> Bootstrap framework.
>>>
>>> Demonstration of Phobos documentation using bootDoc
>>>
>>> http://jakobovrum.github.com/bootdoc-phobos/
>>
>> Very nice!
>>
>> But why the symbols inside std.algorithm, for instance, are not sorted?
>>
>> http://jakobovrum.github.com/bootdoc-phobos/std.algorithm.html
>>
>> (they are kind of sorted by chunks...)
>
> The symbols in the symbol tree appear in the order the symbols appear in
> the documentation, which is the order of declaration in the original
> source (DMD does it this way). I think it would be a little confusing if
> the symbol tree was alphabetically sorted, while the main documentation
> was in order of declaration.
>
> It is possible to rearrange everything with JavaScript of course, but...
> I think this might be going a little bit too far.
>
> What do you think?

I don't think the main documentation order is right in the first place. 
If a module provides many functions, like std.algorithm, I don't see how 
there could possibly be an "intended" order, like "these are more likely 
to be used".

In any case, if I want to quickly find a function, for example "remove" 
or "insert" or something I think might have the name I'm looking for, 
alphabetical order is the best way to go.

>
>> Now if it only had cross references... :-P
>
> If I understand you correctly, any kind of automatic cross-referencing
> would need post-processing of DMD's generated output. I am considering
> such post-processing, but it would massively change the project (a lot
> less would require JavaScript), and completely bind the project to the
> included generator tool.
>
> I think the tool needs more trial-by-fire testing to determine whether
> it's good enough to be mandatory.

Oh, I just said that because I have a pull request waiting for that 
feature to be incorporated in DMD... but I don't think it'll happen...