www.digitalmars.com         C & C++   DMDScript  

digitalmars.D.announce - bootDoc - advanced DDoc framework using Twitter's Bootstrap

reply "Jakob Ovrum" <jakobovrum gmail.com> writes:
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/

LuaD's official documentation also uses bootDoc

     http://jakobovrum.github.com/LuaD/

bootDoc is designed to be easily usable with any project. It is 
used as a git-submodule in both of the above sample scenarios. 
All project-specific settings are provided by a separate 
configuration file (settings.ddoc), which is documented on the 
project's Github wiki.

bootDoc includes a general-purpose generation script. See the 
readme on Github for usage information. The script uses a 
candyDoc-style modules.ddoc as input, making the transition from 
candyDoc projects easy.

Note about noscript: JavaScript is used to get around the static 
nature of DDoc. The sidebar does not work without JavaScript, and 
neither do fully qualified anchor names. However, anchors with 
ambiguous names (such as those usable for symbols on dlang.org) 
work both with and without JavaScript, with the same limitations.

Comments, issues, enhancement requests, questions or rants about 
JavaScript - all feedback is much appreciated!
May 02 2012
next sibling parent Jacob Carlborg <doob me.com> writes:
On 2012-05-02 20:26, 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.



Looks good.

-- 
/Jacob Carlborg
May 02 2012
prev sibling next sibling parent Dmitry Olshansky <dmitry.olsh gmail.com> writes:
On 02.05.2012 22:26, Jakob Ovrum wrote:


 Note about noscript: JavaScript is used to get around the static nature
 of DDoc. The sidebar does not work without JavaScript, and neither do
 fully qualified anchor names. However, anchors with ambiguous names
 (such as those usable for symbols on dlang.org) work both with and
 without JavaScript, with the same limitations.



Wooha! remove in std.algorithm finally points to _function_.
Impressed :)
(BTW It's still "points" to enum in dlang.org)


 Comments, issues, enhancement requests, questions or rants about
 JavaScript - all feedback is much appreciated!




-- 
Dmitry Olshansky
May 02 2012
prev sibling next sibling parent "Masahiro Nakagawa" <repeatedly gmail.com> writes:
On Wednesday, 2 May 2012 at 18:26:11 UTC, 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/

 LuaD's official documentation also uses bootDoc

     http://jakobovrum.github.com/LuaD/

 bootDoc is designed to be easily usable with any project. It is 
 used as a git-submodule in both of the above sample scenarios. 
 All project-specific settings are provided by a separate 
 configuration file (settings.ddoc), which is documented on the 
 project's Github wiki.

 bootDoc includes a general-purpose generation script. See the 
 readme on Github for usage information. The script uses a 
 candyDoc-style modules.ddoc as input, making the transition 
 from candyDoc projects easy.

 Note about noscript: JavaScript is used to get around the 
 static nature of DDoc. The sidebar does not work without 
 JavaScript, and neither do fully qualified anchor names. 
 However, anchors with ambiguous names (such as those usable for 
 symbols on dlang.org) work both with and without JavaScript, 
 with the same limitations.

 Comments, issues, enhancement requests, questions or rants 
 about JavaScript - all feedback is much appreciated!



Great!
I will try this :)


Masahiro
May 02 2012
prev sibling next sibling parent reply "Nick Sabalausky" <SeeWebsiteToContactMe semitwist.com> writes:
While it would be nice if the nav tree were still there w/o JS, and I'm not 
personally a fan of CSS(or HTML)-based "frames", this is definitely a very 
nice, clean, great-looking theme!
May 02 2012
parent "Nick Sabalausky" <SeeWebsiteToContactMe semitwist.com> writes:
"Jakob Ovrum" <jakobovrum gmail.com> wrote in message 
news:lbskaseedspulyynaqlb forum.dlang.org...

 On Wednesday, 2 May 2012 at 21:42:21 UTC, Nick Sabalausky wrote:

 While it would be nice if the nav tree were still there w/o JS, and I'm 
 not
 personally a fan of CSS(or HTML)-based "frames", this is definitely a 
 very
 nice, clean, great-looking theme!



 Alright, with some effort, I made it so that at least a basic module list 
 works without JS. It looks pretty alright with noscript now.



Very nice :)
May 02 2012
prev sibling next sibling parent "Jakob Ovrum" <jakobovrum gmail.com> writes:
On Wednesday, 2 May 2012 at 21:42:21 UTC, Nick Sabalausky wrote:

 While it would be nice if the nav tree were still there w/o JS, 
 and I'm not
 personally a fan of CSS(or HTML)-based "frames", this is 
 definitely a very
 nice, clean, great-looking theme!



Alright, with some effort, I made it so that at least a basic 
module list works without JS. It looks pretty alright with 
noscript now.
May 02 2012
prev sibling next sibling parent reply "James Miller" <james aatch.net> writes:
On Wednesday, 2 May 2012 at 18:26:11 UTC, 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.



I would make a minor change that lets you see the function tree 
near the top. On my laptop screen (about a standard size) I have 
to scroll down about an entire screen to see it. How this is 
implemented is up to you, but being able to collapse to module 
view might be enough.

--
James Miller
May 02 2012
parent reply Jacob Carlborg <doob me.com> writes:
On 2012-05-03 08:09, Jakob Ovrum wrote:


 I am considering putting the module tree and symbol tree in tabs instead
 of below each other.



I think that would be a good idea.

-- 
/Jacob Carlborg
May 03 2012
parent reply Ary Manzana <ary esperanto.org.ar> writes:
On 5/3/12 2:10 PM, Jacob Carlborg wrote:

 On 2012-05-03 08:09, Jakob Ovrum wrote:


 I am considering putting the module tree and symbol tree in tabs instead
 of below each other.



 I think that would be a good idea.



I'm not sure. I'd like the symbols to be under the same tree.

With tabs you'd have to click twice to go from one place to another.
May 03 2012
parent reply Jacob Carlborg <doob me.com> writes:
On 2012-05-03 10:09, Ary Manzana wrote:


 I'm not sure. I'd like the symbols to be under the same tree.

 With tabs you'd have to click twice to go from one place to another.



I didn't even know the symbols where there until a scrolled down.

-- 
/Jacob Carlborg
May 03 2012
parent reply Ary Manzana <ary esperanto.org.ar> writes:
On 5/3/12 6:41 PM, Jacob Carlborg wrote:

 On 2012-05-03 10:09, Ary Manzana wrote:


 I'm not sure. I'd like the symbols to be under the same tree.

 With tabs you'd have to click twice to go from one place to another.



 I didn't even know the symbols where there until a scrolled down.



The same happened to me.

What I meant with "under the same tree is"

+ std
   + algorithm
     * map
     * reduce
     * ...
May 03 2012
next sibling parent Jacob Carlborg <doob me.com> writes:
 What I meant with "under the same tree is"

 + std
 + algorithm
 * map
 * reduce
 * ...



Aha, I was thinking more like "below the tree" as it is now.

-- 
/Jacob Carlborg
May 03 2012
prev sibling parent reply Jacob Carlborg <doob me.com> writes:
On 2012-05-03 14:43, Jakob Ovrum wrote:


 There would be a lot of wasted whitespace to the left, and overflow for
 long symbol names would become an even bigger issue.

 I do understand the problem though, and I want to fix it. Some more
 opinions are much appreciated.



The right side is pretty empty if you have a wide screen. Perhaps the 
symbols can be placed there.

-- 
/Jacob Carlborg
May 03 2012
parent Jacob Carlborg <doob me.com> writes:
On 2012-05-04 16:04, Jakob Ovrum wrote:

 On Thursday, 3 May 2012 at 14:27:38 UTC, Jacob Carlborg wrote:

 The right side is pretty empty if you have a wide screen. Perhaps the
 symbols can be placed there.



 On my current 16:9 1080p monitor, the full width of the page is utilized
 by the main documentation, tested with Opera and Chrome (as it's
 supposed to do with the current use of Bootstrap's "table" framework).
 It does depend on the quantity of documentation though; for LuaD, the
 right side is considerably more empty than for most Phobos modules.

 I think it's possible to conditionally and cleanly introduce a
 right-side sidebar depending on the screen width, that could be worth
 experimenting with.

 First I think I want to try to make the sidebar into an accordion, as
 was suggested earlier in the thread.



Well, it's not empty but the main content doesn't need to be that wide. 
At least not on my screen, 1920x1080.

-- 
/Jacob Carlborg
May 04 2012
prev sibling next sibling parent reply Ary Manzana <ary esperanto.org.ar> writes:
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...)

Now if it only had cross references... :-P
May 02 2012
parent reply Ary Manzana <ary esperanto.org.ar> writes:
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...
May 02 2012
parent Jacob Carlborg <doob me.com> writes:
On 2012-05-03 08:53, Ary Manzana wrote:


 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...



I really hope we get this functionality.

-- 
/Jacob Carlborg
May 03 2012
prev sibling next sibling parent "Jakob Ovrum" <jakobovrum gmail.com> writes:
On Thursday, 3 May 2012 at 05:14:43 UTC, James Miller wrote:

 On Wednesday, 2 May 2012 at 18:26:11 UTC, 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.



 I would make a minor change that lets you see the function tree 
 near the top. On my laptop screen (about a standard size) I 
 have to scroll down about an entire screen to see it. How this 
 is implemented is up to you, but being able to collapse to 
 module view might be enough.

 --
 James Miller



Packages in the module view are collapsable, just click on them.

Having the module list in its entirety collapsable might be an 
idea, but unless your project has a ton of top-level packages and 
modules, it won't help much with your specific problem (the 
situation would be almost the same).

I am considering putting the module tree and symbol tree in tabs 
instead of below each other.
May 02 2012
prev sibling next sibling parent "Jakob Ovrum" <jakobovrum gmail.com> writes:
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?


 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.
May 02 2012
prev sibling next sibling parent Rory McGuire <rjmcguire gmail.com> writes:
--e89a8f642a684b72e104bf1d6c59
Content-Type: text/plain; charset=UTF-8

Would be great if you could make it an accordion with a live search at the
top.


On Thu, May 3, 2012 at 10:09 AM, Ary Manzana <ary esperanto.org.ar> wrote:


 On 5/3/12 2:10 PM, Jacob Carlborg wrote:


 On 2012-05-03 08:09, Jakob Ovrum wrote:

  I am considering putting the module tree and symbol tree in tabs instead

 of below each other.



 I think that would be a good idea.



 I'm not sure. I'd like the symbols to be under the same tree.

 With tabs you'd have to click twice to go from one place to another.



--e89a8f642a684b72e104bf1d6c59
Content-Type: text/html; charset=UTF-8
Content-Transfer-Encoding: quoted-printable

Would be great if you could make it an accordion with a live search at the =
top.<br>
<br><br><div class=3D"gmail_quote">On Thu, May 3, 2012 at 10:09 AM, Ary Man=
zana <span dir=3D"ltr">&lt;<a href=3D"mailto:ary esperanto.org.ar" target=
=3D"_blank">ary esperanto.org.ar</a>&gt;</span> wrote:<br><blockquote class=
=3D"gmail_quote" style=3D"margin:0 0 0 .8ex;border-left:1px #ccc solid;padd=
ing-left:1ex">
<div class=3D"im">On 5/3/12 2:10 PM, Jacob Carlborg wrote:<br>
<blockquote class=3D"gmail_quote" style=3D"margin:0 0 0 .8ex;border-left:1p=
x #ccc solid;padding-left:1ex">
On 2012-05-03 08:09, Jakob Ovrum wrote:<br>
<br>
<blockquote class=3D"gmail_quote" style=3D"margin:0 0 0 .8ex;border-left:1p=
x #ccc solid;padding-left:1ex">
I am considering putting the module tree and symbol tree in tabs instead<br=



</blockquote>
<br>
I think that would be a good idea.<br>
</blockquote>
<br></div>
I&#39;m not sure. I&#39;d like the symbols to be under the same tree.<br>
<br>
With tabs you&#39;d have to click twice to go from one place to another.<br=



</blockquote></div><br>

--e89a8f642a684b72e104bf1d6c59--



 May 03 2012



prev sibling next sibling parent  "James Miller" <james aatch.net>  writes:


On Thursday, 3 May 2012 at 06:09:31 UTC, Jakob Ovrum wrote:

 On Thursday, 3 May 2012 at 05:14:43 UTC, James Miller wrote:

 On Wednesday, 2 May 2012 at 18:26:11 UTC, 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.



 I would make a minor change that lets you see the function 
 tree near the top. On my laptop screen (about a standard size) 
 I have to scroll down about an entire screen to see it. How 
 this is implemented is up to you, but being able to collapse 
 to module view might be enough.

 --
 James Miller



 Packages in the module view are collapsable, just click on them.

 Having the module list in its entirety collapsable might be an 
 idea, but unless your project has a ton of top-level packages 
 and modules, it won't help much with your specific problem (the 
 situation would be almost the same).

 I am considering putting the module tree and symbol tree in 
 tabs instead of below each other.



Ahh, I missed that, sorry. Nevermind me, carry on, you're awesome.

--
James Miller



 May 03 2012



prev sibling next sibling parent  "Jakob Ovrum" <jakobovrum gmail.com>  writes:


On Thursday, 3 May 2012 at 12:33:33 UTC, Ary Manzana wrote:

 On 5/3/12 6:41 PM, Jacob Carlborg wrote:

 On 2012-05-03 10:09, Ary Manzana wrote:


 I'm not sure. I'd like the symbols to be under the same tree.

 With tabs you'd have to click twice to go from one place to 
 another.



 I didn't even know the symbols where there until a scrolled 
 down.



 The same happened to me.

 What I meant with "under the same tree is"

 + std
   + algorithm
     * map
     * reduce
     * ...



There would be a lot of wasted whitespace to the left, and 
overflow for long symbol names would become an even bigger issue.

I do understand the problem though, and I want to fix it. Some 
more opinions are much appreciated.



 May 03 2012



prev sibling next sibling parent  "Steven Schveighoffer" <schveiguy yahoo.com>  writes:


On Thu, 03 May 2012 08:43:43 -0400, Jakob Ovrum <jakobovrum gmail.com>  
wrote:


 On Thursday, 3 May 2012 at 12:33:33 UTC, Ary Manzana wrote:

 On 5/3/12 6:41 PM, Jacob Carlborg wrote:

 On 2012-05-03 10:09, Ary Manzana wrote:


 I'm not sure. I'd like the symbols to be under the same tree.

 With tabs you'd have to click twice to go from one place to another.



 I didn't even know the symbols where there until a scrolled down.



 The same happened to me.

 What I meant with "under the same tree is"

 + std
   + algorithm
     * map
     * reduce
     * ...



 There would be a lot of wasted whitespace to the left, and overflow for  
 long symbol names would become an even bigger issue.

 I do understand the problem though, and I want to fix it. Some more  
 opinions are much appreciated.



I suggest:

1. Only expand tree to the level of the current symbol selected.  So for  
instance, you click on std.datetime, you see all the top-level symbols of  
std.datetime *not* expanded.  If you click on std.datetime.Month, the  
Month enum expands in the tree.
2. When inside a module, only show the packages of that module as  
breadcrumbs, without indentation.  That saves you the white space.

BTW, I noticed two issues:

1. If a symbol name is too long, it is truncated with ..., but the  
expand/collapse arrow is also removed.
2. The index.html goes to links like std_base64.html, but the actual doc  
is at std.base64.html, so you get a 404.

Looks really nice!  I agree with Ary, we *really* really need cross  
references (generated by the compiler), and I'd add it would be nice to be  
able to show categories and category headers at the top of each module  
(i.e. here are all the structs in this file, here are all the classes).

-Steve



 May 03 2012



prev sibling next sibling parent  "Jakob Ovrum" <jakobovrum gmail.com>  writes:


On Thursday, 3 May 2012 at 14:30:38 UTC, Steven Schveighoffer 
wrote:

 I suggest:

 1. Only expand tree to the level of the current symbol 
 selected.  So for instance, you click on std.datetime, you see 
 all the top-level symbols of std.datetime *not* expanded.  If 
 you click on std.datetime.Month, the Month enum expands in the 
 tree.



You mean like the module list currently works with packages and 
modules?


 2. When inside a module, only show the packages of that module 
 as breadcrumbs, without indentation.  That saves you the white 
 space.



Packages of a module?

I'm not sure what you mean here, could you try to explain this 
again, perhaps with an example? I have a feeling it's a good 
idea, so I want to comprehend it fully.


 BTW, I noticed two issues:

 1. If a symbol name is too long, it is truncated with ..., but 
 the expand/collapse arrow is also removed.



Added a comment to an existing issue, thanks.

https://github.com/JakobOvrum/bootDoc/issues/1


 2. The index.html goes to links like std_base64.html, but the 
 actual doc is at std.base64.html, so you get a 404.



The links on the index page are generated from hard-coded HTML in 
index.d. With the new fix for the noscript sidebar, file names 
must use a dot as a package separator, while the hard-coded paths 
use an underscore (the package separator in output files is 
configurable, by the way). Previously the links incidentally 
worked because the output was configured with underscores.

So the problem really lies with the Phobos documentation for 
using hard-coded links. I think the noscript sidebar is more 
important than the (terribly outdated) index page, which could be 
fixed by editing the source anyway (I suppose I could easily do 
this for the Phobos bootDoc demo).



 May 04 2012



prev sibling next sibling parent  "Jakob Ovrum" <jakobovrum gmail.com>  writes:


On Thursday, 3 May 2012 at 14:27:38 UTC, Jacob Carlborg wrote:

 The right side is pretty empty if you have a wide screen. 
 Perhaps the symbols can be placed there.



On my current 16:9 1080p monitor, the full width of the page is 
utilized by the main documentation, tested with Opera and Chrome 
(as it's supposed to do with the current use of Bootstrap's 
"table" framework). It does depend on the quantity of 
documentation though; for LuaD, the right side is considerably 
more empty than for most Phobos modules.

I think it's possible to conditionally and cleanly introduce a 
right-side sidebar depending on the screen width, that could be 
worth experimenting with.

First I think I want to try to make the sidebar into an 
accordion, as was suggested earlier in the thread.



 May 04 2012



prev sibling next sibling parent  "Jakob Ovrum" <jakobovrum gmail.com>  writes:


On Thursday, 3 May 2012 at 08:16:48 UTC, Rory McGuire wrote:

 Would be great if you could make it an accordion with a live 
 search at the
 top.



An accordion is a nice idea, and Bootstrap has good support for 
it.

Where would you have the search, exactly, though? And do you mean 
the existing symbol search, a project-wide search (which is 
non-trivial), or a module search?



 May 04 2012



prev sibling next sibling parent  "Jakob Ovrum" <jakobovrum gmail.com>  writes:


On Thursday, 3 May 2012 at 06:53:42 UTC, Ary Manzana wrote:

 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.



I agree that the current order doesn't make a whole lot of sense, 
but it's something that requires one of three things; either 1) a 
patch to DDoc to make it emit declarations in a different order, 
or 2) post-processing of DDoc's output, or 3) dynamic reordering 
with JavaScript.

Although it's actually quite trivial to implement (especially 
with jQuery), I don't like the sound of #3.

The problem I have with #2 is that it indicates a problem with 
the documentation generator in the first place (DMD's DDoc 
implementation). I'd rather have a go at making a better DDoc 
generator (maybe Descent is a good start? A new project using SDC 
is another option) than go down route #2.



 May 04 2012



prev sibling next sibling parent  "Steven Schveighoffer" <schveiguy yahoo.com>  writes:


On Fri, 04 May 2012 09:56:48 -0400, Jakob Ovrum <jakobovrum gmail.com>  
wrote:


 On Thursday, 3 May 2012 at 14:30:38 UTC, Steven Schveighoffer wrote:

 I suggest:

 1. Only expand tree to the level of the current symbol selected.  So  
 for instance, you click on std.datetime, you see all the top-level  
 symbols of std.datetime *not* expanded.  If you click on  
 std.datetime.Month, the Month enum expands in the tree.



 You mean like the module list currently works with packages and modules?



I don't see it working that way.  If I click on etc.c.sqlite3 for example,  
it doesn't collapse std.

Essentially, what I mean is, I should only see the parents, immediate  
children, and siblings of the currently selected item in the tree *by  
default*, and then let the user expand if he's interested in more.  I only  
suggest this for the module, though.

For example, std.datetime has a huge tree, but everything is expanded  
fully.  If all the top-level items are collapsed, then I don't have to go  
as far to navigate for something.


 2. When inside a module, only show the packages of that module as  
 breadcrumbs, without indentation.  That saves you the white space.



 Packages of a module?



packages that a module is in.  For example, etc.c.sqlite3 is in packages  
etc and c.  If we make those breadcrumbs instead of part of a large tree,  
it can get around your worry about whitespace, because they don't need  
separate indentation.


 2. The index.html goes to links like std_base64.html, but the actual  
 doc is at std.base64.html, so you get a 404.



 The links on the index page are generated from hard-coded HTML in  
 index.d. With the new fix for the noscript sidebar, file names must use  
 a dot as a package separator, while the hard-coded paths use an  
 underscore (the package separator in output files is configurable, by  
 the way). Previously the links incidentally worked because the output  
 was configured with underscores.

 So the problem really lies with the Phobos documentation for using  
 hard-coded links. I think the noscript sidebar is more important than  
 the (terribly outdated) index page, which could be fixed by editing the  
 source anyway (I suppose I could easily do this for the Phobos bootDoc  
 demo).



OK, not a big deal then.  Part of the problem with phobos ddoc in this  
regard is that cross-links are defined in each individual module.

-Steve



 May 04 2012



prev sibling next sibling parent  "Jakob Ovrum" <jakobovrum gmail.com>  writes:


On Friday, 4 May 2012 at 14:48:04 UTC, Steven Schveighoffer wrote:

 I don't see it working that way.  If I click on etc.c.sqlite3 
 for example, it doesn't collapse std.

 Essentially, what I mean is, I should only see the parents, 
 immediate children, and siblings of the currently selected item 
 in the tree *by default*, and then let the user expand if he's 
 interested in more.  I only suggest this for the module, though.

 For example, std.datetime has a huge tree, but everything is 
 expanded fully.  If all the top-level items are collapsed, then 
 I don't have to go as far to navigate for something.



Right, I didn't notice that problem, but it is indeed glaringly 
obvious with std.datetime. Will fix that, thanks!


 packages that a module is in.  For example, etc.c.sqlite3 is in 
 packages etc and c.  If we make those breadcrumbs instead of 
 part of a large tree, it can get around your worry about 
 whitespace, because they don't need separate indentation.



That's a great idea, but where in the tree would it appear? What 
would happen to the rest of the modules, should they be indented 
like they are now? Wouldn't that look a little weird?



 May 04 2012



prev sibling next sibling parent  "Steven Schveighoffer" <schveiguy yahoo.com>  writes:


On Fri, 04 May 2012 10:59:46 -0400, Jakob Ovrum <jakobovrum gmail.com>  
wrote:


 On Friday, 4 May 2012 at 14:48:04 UTC, Steven Schveighoffer wrote:


 packages that a module is in.  For example, etc.c.sqlite3 is in  
 packages etc and c.  If we make those breadcrumbs instead of part of a  
 large tree, it can get around your worry about whitespace, because they  
 don't need separate indentation.



 That's a great idea, but where in the tree would it appear? What would  
 happen to the rest of the modules, should they be indented like they are  
 now? Wouldn't that look a little weird?



I was envisioning eliminating the rest of the tree, and you'd have to  
click on one of the breadcrumbs to get it back.  But that might be weird.

Something like:

etc . c .
sqlite3
* func1
* func2
...

And then you click on etc or c, and get the module tree back (either  
dynamically or after a round-trip from the server).

The idea is, when you are navigating in a module, you are interested in  
the module, not the rest of the modules.

I personally am not as much concerned about how many clicks it takes to  
navigate as much as I'm concerned about making the tree more focused on  
what you are doing now.

-Steve



 May 04 2012



prev sibling next sibling parent  "Jakob Ovrum" <jakobovrum gmail.com>  writes:


On Friday, 4 May 2012 at 15:11:39 UTC, Steven Schveighoffer wrote:

 I was envisioning eliminating the rest of the tree, and you'd 
 have to click on one of the breadcrumbs to get it back.  But 
 that might be weird.

 Something like:

 etc . c .
 sqlite3
 * func1
 * func2
 ...

 And then you click on etc or c, and get the module tree back 
 (either dynamically or after a round-trip from the server).

 The idea is, when you are navigating in a module, you are 
 interested in the module, not the rest of the modules.

 I personally am not as much concerned about how many clicks it 
 takes to navigate as much as I'm concerned about making the 
 tree more focused on what you are doing now.

 -Steve



I think that's an awesome idea, I'll play with it later. Thanks.



 May 04 2012



prev sibling next sibling parent  Rory McGuire <rjmcguire gmail.com>  writes:


--e89a8f64715bcf2d5904bf389c49
Content-Type: text/plain; charset=UTF-8

I would put a text input above the accordian, with the word "Filter
Module" or something like that.
It would be great if it were possible to search the module too or perhaps a
module description of some sort, but that is more work.

The purpose for the text input filter on the accordian would just be to
show module names for quicker navigation, esp if the text box was selected
on page load.

On Fri, May 4, 2012 at 2:07 PM, Jakob Ovrum <jakobovrum gmail.com> wrote:


 On Thursday, 3 May 2012 at 08:16:48 UTC, Rory McGuire wrote:


 Would be great if you could make it an accordion with a live search at the
 top.



 An accordion is a nice idea, and Bootstrap has good support for it.

 Where would you have the search, exactly, though? And do you mean the
 existing symbol search, a project-wide search (which is non-trivial), or a
 module search?



--e89a8f64715bcf2d5904bf389c49
Content-Type: text/html; charset=UTF-8
Content-Transfer-Encoding: quoted-printable

I would put a text input above the accordian, with the word &quot;Filter=C2=
=A0
Module&quot; or something like that.<div>It would be great if it were possi=
ble to search the module too or perhaps a module description of some sort, =
but that is more work.</div><div><br></div><div>
The purpose for the text input filter on the accordian would just be to sho=
w module names for quicker navigation, esp if the text box was selected on =
page load.<br><br><div class=3D"gmail_quote">On Fri, May 4, 2012 at 2:07 PM=
, Jakob Ovrum <span dir=3D"ltr">&lt;<a href=3D"mailto:jakobovrum gmail.com"=
 target=3D"_blank">jakobovrum gmail.com</a>&gt;</span> wrote:<br>
<blockquote class=3D"gmail_quote" style=3D"margin:0 0 0 .8ex;border-left:1p=
x #ccc solid;padding-left:1ex"><div class=3D"im">On Thursday, 3 May 2012 at=
 08:16:48 UTC, Rory McGuire wrote:<br>
<blockquote class=3D"gmail_quote" style=3D"margin:0 0 0 .8ex;border-left:1p=
x #ccc solid;padding-left:1ex">
Would be great if you could make it an accordion with a live search at the<=
br>
top.<br>
</blockquote>
<br></div>
An accordion is a nice idea, and Bootstrap has good support for it.<br>
<br>
Where would you have the search, exactly, though? And do you mean the exist=
ing symbol search, a project-wide search (which is non-trivial), or a modul=
e search?<br>
</blockquote></div><br></div>

--e89a8f64715bcf2d5904bf389c49--



 May 04 2012



prev sibling next sibling parent  Dejan Lekic <dejan.lekic gmail.com>  writes:


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/
 
 LuaD's official documentation also uses bootDoc
 
      http://jakobovrum.github.com/LuaD/
 
 bootDoc is designed to be easily usable with any project. It is
 used as a git-submodule in both of the above sample scenarios.
 All project-specific settings are provided by a separate
 configuration file (settings.ddoc), which is documented on the
 project's Github wiki.
 
 bootDoc includes a general-purpose generation script. See the
 readme on Github for usage information. The script uses a
 candyDoc-style modules.ddoc as input, making the transition from
 candyDoc projects easy.
 
 Note about noscript: JavaScript is used to get around the static
 nature of DDoc. The sidebar does not work without JavaScript, and
 neither do fully qualified anchor names. However, anchors with
 ambiguous names (such as those usable for symbols on dlang.org)
 work both with and without JavaScript, with the same limitations.
 
 Comments, issues, enhancement requests, questions or rants about
 JavaScript - all feedback is much appreciated!



As I said on irc://irc.freenode.org/d , this is probably the best DDoc theme 
I have seen so far. So nice, and elegant.

I have it bookmarked the moment he gave us the link on #D channel. :)

Well-done!



 May 07 2012



prev sibling  parent  "Jonas Drewsen" <jdrewsen nospam.com>  writes:


I guess most devs have a pretty wide screen. How about letting 
the overview of the current selected module be located to the 
right of the modules listing when there is enough horizontal 
space. Something like:

http://dl.dropbox.com/u/188292/flow.png

I guess that it could be accomplished by using left floats and 
min-widths in order not to break it for people with smaller 
screens.

/Jonas



 May 08 2012