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