digitalmars.D.learn - Fix gtkD api display
- Johnson Jones (41/41) Aug 03 2017 https://api.gtkd.org
- Johnson Jones (11/11) Aug 03 2017 Also, interfaces are not linkable.
- Adam D. Ruppe (8/9) Aug 04 2017 So I ran gtkd through my doc generator too
- Johnson Jones (46/54) Aug 04 2017 Looks nicer in some ways and in others I prefer the original.
- Adam D. Ruppe (31/47) Aug 04 2017 Yeah, there is no overview page in the source code... but I can
- Johnson Jones (168/217) Aug 04 2017 Yeah, that is a nice feature. But I do not think we are talking
- Mike Wey (7/58) Aug 04 2017 Improving the documentation is something i want to do but there are
- Gerald (9/13) Aug 04 2017 Mike I had contributed the makeddox.sh script awhile ago, it
- Johnson Jones (3/17) Aug 04 2017 Is there any online demo of it working?
- Gerald (2/17) Aug 04 2017 Unfortunately there is not, I just run it locally on my laptop.
- Mike Wey (14/29) Aug 05 2017 One issue is the shear size of the generated documentation, though the
- Adam D. Ruppe (14/23) Aug 10 2017 what?! I'm not actually sure how much gtk alone takes, but my
- Mike Wey (14/42) Aug 10 2017 The problem was that there are a few large classes at the start of the
- Adam D. Ruppe (9/16) Aug 10 2017 Oh, I see. My generator lists them on the index, but doesn't
- Antonio (5/17) Aug 11 2017 Hi,
https://api.gtkd.org It is difficult to navigate. 1. clicking the documentation on the main site takes it to the gtk.AboutDialog api. That is all it shows, I was confused at first, as I'm sure most people would be. 2. The packages list lists all the packages, but all the sub elements are expanded, making it time consuming to hunt down anything specific. Initially collapsing them and adding a search box would be nice. 3. When clicking on any packages it reloads the page and shows only the package in the first tab. This requires one to then go back to packages and hunt for something else again. Because the position of the scroll is not saved, one has to scroll down through the entire list. It would be better, I think, if it was one single tab all in a single hierarchy that never reloaded the page so that it is easier to navigate quickly. e.g., instead of Package atk atk.ActionIF atk.Action ... we have atk atk.ActionIF GetActionStruct GetStruct ... atk.Action ... ... and so effectually combining both tabs. It should solve the issues that the current way has without really causing any problems. Everything should be collapsed by default and since no reloading of the page should occur(which might require having the api descriptions in a separate frame that is loaded separately on package changes to avoid reloading the tree view which will recollapse everything). It will make navigating the gtkD api much more fun ;)
Aug 03 2017
Also, interfaces are not linkable. e.g., for gtk.ApplicationWindow, it inherits from gtk.Window but I have to go back to the packages and scroll down to find gtk.Window to see it's properties and methods. Would be nice if I could just click on the gtk.Window and it jump me to it. https://api.gtkd.org/gtkd/gtk/ApplicationWindow.html class ApplicationWindow : gtk.Window.Window, gio.ActionGroupIF.ActionGroupIF, gio.ActionMapIF.ActionMapIF; since the hierarchy is gtk/Window/Window, click on gtk should take one to the gtk package, the first Window should take one to gtk.Window and the second should take one to gtk.Window.Window
Aug 03 2017
On Friday, 4 August 2017 at 02:08:31 UTC, Johnson Jones wrote:https://api.gtkd.org/gtkd/gtk/ApplicationWindow.htmlSo I ran gtkd through my doc generator too http://dpldocs.info/experimental-docs/gtk.ApplicationWindow.ApplicationWindow.html and I didn't make a top-level package file either... but doing that wouldn't be hard. However, I noticed it is basically the same as the official C documents: https://developer.gnome.org/gtk3/stable/GtkApplicationWindow.html so idk if it is worth spending a lot of time on it.
Aug 04 2017
On Friday, 4 August 2017 at 13:59:11 UTC, Adam D. Ruppe wrote:On Friday, 4 August 2017 at 02:08:31 UTC, Johnson Jones wrote:Looks nicer in some ways and in others I prefer the original. I particularly like the members list. The use of the different font sizes, colors, and boxes/lines help contrast elements well. When I click on gtk on the link you gave it gives basically an empty page(a single module). If I click on ApplicationWindow it takes me to a page that lists all the members on the left, which is nice. Probably minor bugs or issues. e.g., http://dpldocs.info/experimental-docs/gtk.HButtonBox.HButtonBox.html Does not list any members to the left. The left list should be an independent panel. When one scrolls down to view a long page one doesn't want to have to scroll all the way back up to view the members list again. It results in a slower process. Seems that is how many of the D docs are but it's wrong/unnecessary as it slows searching down. e.g., the original gtkD docs have a scrollable panel like I'm talking about, but they just list one module at a time, which makes it difficult: https://api.gtkd.org/gtkd/gtk/AboutDialog.html and https://developer.gnome.org/gtk3/stable/GtkApplicationWindow.html has no side panel. So, with a little tightening up, I'd definitely prefer your docs over the other two versions. (It's always good to have multiple versions though) I think any type of documentation should aim at two goals: As much information as possible and to quickly access any point in that information from any other point with information points that are closer being more quickly accessed(A metric). The way the info is organized is, of course, going then to be dependent on the above. Since many programs spend a significant portion of their life searching through docs online, I think it's important to optimize that routine. Would be nice if programmers learned to optimize not only programs but the art of programming itself... we'd all get much more done. After all, many of the same principles apply. But things are way better than they used to be, so that's a good sign ;) I'm not sure what Geralds docs look like but it might solve many of the problems already and you don't have to waste your time if you don't want to. OTH, since you are using an automated utility, it might be worth while to optimize it a little more since it will effect everything it's used on(although, I don't know how time consuming it would be to rerun it on all the docs you've generated... hopefully you've automated that too ;). Thanks.https://api.gtkd.org/gtkd/gtk/ApplicationWindow.htmlSo I ran gtkd through my doc generator too http://dpldocs.info/experimental-docs/gtk.ApplicationWindow.ApplicationWindow.html and I didn't make a top-level package file either... but doing that wouldn't be hard. However, I noticed it is basically the same as the official C documents: https://developer.gnome.org/gtk3/stable/GtkApplicationWindow.html so idk if it is worth spending a lot of time on it.
Aug 04 2017
On Friday, 4 August 2017 at 21:53:14 UTC, Johnson Jones wrote:When I click on gtk on the link you gave it gives basically an empty page(a single module).Yeah, there is no overview page in the source code... but I can make it create one automatically.http://dpldocs.info/experimental-docs/gtk.HButtonBox.HButtonBox.html Does not list any members to the left.That's intentional, actually. For the left nav, I show parents and siblings, not children (that's in the main content on the right). I sometimes miss children there too, but siblings are actually usually more useful to me. Easier to see the value in Phobos since it is flatter: http://dpldocs.info/experimental-docs/std.algorithm.sorting.isSorted.html you can see the bolded isSorted showing where you are now, and then its other siblings to navigate the module over there. gtkd has really shallow modules with just one class per module, so this appears less useful... but in general I find it really easily to navigate. Maybe I could detect the one class per module pattern and collapse it though.When one scrolls down to view a long page one doesn't want to have to scroll all the way back up to view the members list again.See, this is why I DON'T use a tree over there. There's just way too much scrolling in a tree, both vertical and horizontal. By just showing parents and siblings, it presents the most useful info without needing scrolling... it just doesn't work well for one class per module.Since many programs spend a significant portion of their life searching through docs online, I think it's important to optimize that routine.That's why I forked the docs... everyone else was just doing the same boring crap so I went something fairly different.I'm not sure what Geralds docs look like but it might solve many of the problems already and you don't have to waste your time if you don't want to.It sounds like ddox which is one option I evaluated and rejected when I did my fork... so it might be ok but I doubt it is better. The official gtk docs are the competition and I don't actually like them either...I don't know how time consuming it would be to rerun it on all the docs you've generated... hopefully you've automated that too ;).Simple case of running ./doc /path/to/gtk and waiting like 5 mins for it. So it is slow but automatic so I can just do it in the background. I just hate running big disk operations on my computer... so I need to optimize this since I run so many docs now.
Aug 04 2017
Johnson Jones <JJ Dynomite.com> On Friday, 4 August 2017 at 23:14:38 UTC, Adam D. Ruppe wrote:On Friday, 4 August 2017 at 21:53:14 UTC, Johnson Jones wrote:Yeah, that is a nice feature. But I do not think we are talking about the same thing. While having the siblings only is also nice and desirable to reduce clutter, one needs to quickly see all methods in a module rather than having to hunt and peck. This is actually done in the phobos link you gave and is what am I talking about. The problem then is that we do not see the hierarchy of all the modules and how they relate without having to click clinks. e.g., http://dpldocs.info/experimental-docs/std.algorithm.sorting.nextPermutation.html but http://dpldocs.info/experimental-docs/std.html shows all the modules in the main view which is very long and takes time to scroll. It would be nice if those were shown in the left pane rather than nothing. This way, instead of having to scroll down the long list to find a module one can see it usually instantaneously to the left. Basically the same as the functions that are listed in the first link. The way I would do it, probably, is to have a complete hierarchy tree. std ... experimental ... allocator ... building_blocks ... region ... InSituRegion Now, obviously this is a very big list. (For speed, probably ajax would be used to load only the most relevant) Also, everything cannot be expanded at the start. Only the most current position is expanded + any siblings. So, it is sorta like what you have but offers a way to see the entire library and navigate it relatively quickly but without having to leave that panel to find something. It's all their, just not the descriptions, etc.(although mouse over could provide some basic description when required) Because humans are amazing and have figured out vast ways to do things, I'd probably have a small toolbar at the top that lets one go between different views. If you want a flat list you click the flat button. If you want a full hierarchy you can click a button for that. If you want a reduced hierarchy(immediate module only, still in tree form but all the other branches off the root are not shown) you could get that. Siblings only would have a button. Since all these are basically just different "views" of the same data, they all have their pros and cons and some are more useful than others at different times. The more ways one can view data the more ways one can understand the data.When I click on gtk on the link you gave it gives basically an empty page(a single module).Yeah, there is no overview page in the source code... but I can make it create one automatically.http://dpldocs.info/experimental-docs/gtk.HButtonBox.HButtonBox.html Does not list any members to the left.That's intentional, actually. For the left nav, I show parents and siblings, not children (that's in the main content on the right). I sometimes miss children there too, but siblings are actually usually more useful to me. Easier to see the value in Phobos since it is flatter: http://dpldocs.info/experimental-docs/std.algorithm.sorting.isSorted.html you can see the bolded isSorted showing where you are now, and then its other siblings to navigate the module over there.gtkd has really shallow modules with just one class per module, so this appears less useful... but in general I find it really easily to navigate. Maybe I could detect the one class per module pattern and collapse it though.My problem with gtkD's docs is that one cannot quickly(within a click) go from one module to another. One must select the packages tab then find the module and click on it. Do whatever, then when one wants to go to another module, repeat the process. It's not slow in an absolute sense(whatever that means) but it takes a few seconds when it can be done < 1s. Since the packages and module are tabbed, one can't have them both open. If they were side by side, it would probably work fine... not much different than a tree view. Also, the package tree is not collapsed by default. This means more scrolling. Scrolling is a slow process. It may seems fast but it's just a waste of time ultimately because we cannot do anything while we are doing it... and all those little scrolls add up to significant time loss. It's similar to how banks try to get a few extra cents per customer because it's billions at the end of the day... or how manufactures try to cut costs on a product that are a few cents work per product but add up to billions. Similar for programmers. Imagine if we could instantly find the help we wanted how much more time we would have over our lives. E.g., some type of brain interface device that we could transmit our thoughts in to and it would do a search for the data and present the results. That is effectively what we have with google or whatever computer searching tools.. but it far slower than a direct connection.I agree, in most cases for programming docs(or file systems, say) this is true. But most of the time the tree should be completely collapsed at all levels so within O(log2(depth)) clicks we can find what we want. Usually the depth is not more than 10 so it takes just a few clicks to find(usually about 3 to 4). These clicks are better than scrolling because to scroll we have to move the cursor to the scroller and then back and click. When we click generally it is a smaller distance to move because the information is localized on the screen(e.g., we click on the parent then on a child which is somewhere below the parent, but usually not too far off). If humans organized things better we wouldn't have such problems. Hierarchies that are effectively a flat list(e.g., a folder with 1M sub-folders in it) is not designed properly for optimal searching and effectively is not a hierarchy. (We end up with O(n) searching rather than O(log(n))).When one scrolls down to view a long page one doesn't want to have to scroll all the way back up to view the members list again.See, this is why I DON'T use a tree over there. There's just way too much scrolling in a tree, both vertical and horizontal. By just showing parents and siblings, it presents the most useful info without needing scrolling... it just doesn't work well for one class per module.That's good, that's what it takes for progress. Most people are lemmings and don't have any imagination and can't or won't think outside the box. Why humans have progressed to where they are is someone being tired of the same old boring and broke shit and decided to find a better way.Since many programs spend a significant portion of their life searching through docs online, I think it's important to optimize that routine.That's why I forked the docs... everyone else was just doing the same boring crap so I went something fairly different.Could you automate this better using a "cloud" based strategy? Something like github or a remote server where you have all the docs uploaded to and can trigger an update which causes it to update the documentation and then a rebuild which builds the docs? This way it should only take a few seconds to start the process and everything will be done remotely not effecting your own time much(of course the design/setup time might be costly but probably not too bad). IMO, the modern documentation sucks. I remember doing win32 stuff back in the day of win95/98 and microsoft had all the docs with visual studio 2005. The documentation was extremely informative rather than just a list of functions and parameter descriptions. They'd give you the theory, the relationships between everything, etc. It wasn't that easy to navigate but it wasn't a big deal because most of the time was spent reading and clicking links. Now, since the actual information is so frugal, one spends more time searching for stuff and therefor the searching time is more of an issue. For example: ---- InSituRegion struct InSituRegion(size_t size, size_t minAlign = platformAlignment) InSituRegion is a convenient region that carries its storage within itself (in the form of a statically-sized array). Region struct Region(ParentAllocator = NullAllocator, uint minAlign = platformAlignment, Flag!"growDownwards" growDownwards = No.growDownwards) A Region allocator allocates memory straight from one contiguous chunk. There is no deallocation, and once the region is full, allocation requests return null. Therefore, Regions are often used (a) in conjunction with more sophisticated allocators; or (b) for batch-style very fast allocations that deallocate everything at once. SbrkRegion struct SbrkRegion(uint minAlign = platformAlignment) Allocator backed by $(LINK2 https://en.wikipedia.org/wiki/Sbrk, sbrk) for Posix systems. Due to the fact that sbrk is not thread-safe by design, SbrkRegion uses a mutex internally. This implies that uncontrolled calls to brk and sbrk may affect the workings of SbrkRegion adversely. ---- Basically tells me nothing about how to use these things nor how they work with the whole design of allocator. It may be somewhat straight forward in some cases but in others it's helpful to know theory. To get that, I have to track down where the information is, if it exists. It is backwards than what it used to be which was a top down approach(a hierarchy starting with the root). e.g., You might start with a section on memory management that describes how it works and all that and it would then break off in to the more detailed aspects and those then would break off. As you learn about them you start with the most general understanding and learn the specifics... which is how the human brain learns. Now we seem to just deal with specifies. Generalities must be learned from other sources and one must try and piece everything together. Of course, this is probably due to isolated individuals writing the docs rather than a team that actually plans out everything... The D docs sorta try to do the top down approach so there is info there but I don't get the same feeling I get from the win32 docs(which, some time later MS$ changed the help system and everything started going down hill). I think it's because the win32 help design was just very well put together. It didn't feel like a cobbling of different statements but a very well thought out explanation of the entire system. In any case, thanks for working on this stuff! It benefits a lot of people.I'm not sure what Geralds docs look like but it might solve many of the problems already and you don't have to waste your time if you don't want to.It sounds like ddox which is one option I evaluated and rejected when I did my fork... so it might be ok but I doubt it is better. The official gtk docs are the competition and I don't actually like them either...I don't know how time consuming it would be to rerun it on all the docs you've generated... hopefully you've automated that too ;).Simple case of running ./doc /path/to/gtk and waiting like 5 mins for it. So it is slow but automatic so I can just do it in the background. I just hate running big disk operations on my computer... so I need to optimize this since I run so many docs now.
Aug 04 2017
On 04-08-17 03:51, Johnson Jones wrote:https://api.gtkd.org It is difficult to navigate. 1. clicking the documentation on the main site takes it to the gtk.AboutDialog api. That is all it shows, I was confused at first, as I'm sure most people would be. 2. The packages list lists all the packages, but all the sub elements are expanded, making it time consuming to hunt down anything specific. Initially collapsing them and adding a search box would be nice. 3. When clicking on any packages it reloads the page and shows only the package in the first tab. This requires one to then go back to packages and hunt for something else again. Because the position of the scroll is not saved, one has to scroll down through the entire list. It would be better, I think, if it was one single tab all in a single hierarchy that never reloaded the page so that it is easier to navigate quickly. e.g., instead of Package atk atk.ActionIF atk.Action ... we have atk atk.ActionIF GetActionStruct GetStruct ... atk.Action ... ... and so effectually combining both tabs. It should solve the issues that the current way has without really causing any problems. Everything should be collapsed by default and since no reloading of the page should occur(which might require having the api descriptions in a separate frame that is loaded separately on package changes to avoid reloading the tree view which will recollapse everything). It will make navigating the gtkD api much more fun ;)Improving the documentation is something i want to do but there are always some more important things to do. Like the Questions/Issues you posted earlier. So unless somebody volunteers it won't happen anytime soon. -- Mike Wey
Aug 04 2017
On Friday, 4 August 2017 at 15:08:27 UTC, Mike Wey wrote:Improving the documentation is something i want to do but there are always some more important things to do. Like the Questions/Issues you posted earlier. So unless somebody volunteers it won't happen anytime soon.Mike I had contributed the makeddox.sh script awhile ago, it generates much nicer documentation then candydocs in my IHMO and includes a nice search box. If there is something lacking in it that needs to be improved before it can be used let me know and I'll do the work. The only issue with it that I am aware of is you need to manually copy the public ddox css into the generated folder. I didn't see an easy way to determine it's location automatically.
Aug 04 2017
On Friday, 4 August 2017 at 15:24:51 UTC, Gerald wrote:On Friday, 4 August 2017 at 15:08:27 UTC, Mike Wey wrote:Is there any online demo of it working? Thanks.Improving the documentation is something i want to do but there are always some more important things to do. Like the Questions/Issues you posted earlier. So unless somebody volunteers it won't happen anytime soon.Mike I had contributed the makeddox.sh script awhile ago, it generates much nicer documentation then candydocs in my IHMO and includes a nice search box. If there is something lacking in it that needs to be improved before it can be used let me know and I'll do the work. The only issue with it that I am aware of is you need to manually copy the public ddox css into the generated folder. I didn't see an easy way to determine it's location automatically.
Aug 04 2017
On Friday, 4 August 2017 at 21:54:26 UTC, Johnson Jones wrote:On Friday, 4 August 2017 at 15:24:51 UTC, Gerald wrote:Unfortunately there is not, I just run it locally on my laptop.On Friday, 4 August 2017 at 15:08:27 UTC, Mike Wey wrote:Is there any online demo of it working?[...]Mike I had contributed the makeddox.sh script awhile ago, it generates much nicer documentation then candydocs in my IHMO and includes a nice search box. If there is something lacking in it that needs to be improved before it can be used let me know and I'll do the work. The only issue with it that I am aware of is you need to manually copy the public ddox css into the generated folder. I didn't see an easy way to determine it's location automatically.
Aug 04 2017
On 04-08-17 17:24, Gerald wrote:On Friday, 4 August 2017 at 15:08:27 UTC, Mike Wey wrote:One issue is the shear size of the generated documentation, though the current version of ddox no longer generates a ton of unused files bringing the size down from 15-20GB to a mere 2GB. So it has at leased become manageable to host it on the VPS that hosts gtkd.org. Now remains figuring out setting up the proper redirects on the server, and a few personal preferences about ddox: The need to go trough the empty module page when browsing the documentation. For a lot / most? functions the complete documentation is in the overview defeating the purpose of the one page per artifact. And im not a big fan of the one page per artifact style of documentation. -- Mike WeyImproving the documentation is something i want to do but there are always some more important things to do. Like the Questions/Issues you posted earlier. So unless somebody volunteers it won't happen anytime soon.Mike I had contributed the makeddox.sh script awhile ago, it generates much nicer documentation then candydocs in my IHMO and includes a nice search box. If there is something lacking in it that needs to be improved before it can be used let me know and I'll do the work. The only issue with it that I am aware of is you need to manually copy the public ddox css into the generated folder. I didn't see an easy way to determine it's location automatically.
Aug 05 2017
On Saturday, 5 August 2017 at 14:02:09 UTC, Mike Wey wrote:One issue is the shear size of the generated documentation, though the current version of ddox no longer generates a ton of unused files bringing the size down from 15-20GB to a mere 2GB.what?! I'm not actually sure how much gtk alone takes, but my entire doc folder is 4 GB, including a good chunk of the dub repo, phobos, druntime, my stuff, search indexes, archives, etc. I guess it is possible the gtkd is 2 GB of that, but at least it isn't 20.The need to go trough the empty module page when browsing the documentation. For a lot / most? functions the complete documentation is in the overview defeating the purpose of the one page per artifact.If you guys are interested, I can do a custom adrdox for gtk that: * reads more of the gtk syntax https://developer.gnome.org/gtk-doc-manual/stable/documenting_syntax.html.en * recognizes the one-item-per-module pattern and skips the empty pages * has a style more like https://gtkd.org/index.html * Maybe a few other little things?And im not a big fan of the one page per artifact style of documentation.Oh, it is so much better in a lot of ways.
Aug 10 2017
On 10-08-17 15:57, Adam D. Ruppe wrote:On Saturday, 5 August 2017 at 14:02:09 UTC, Mike Wey wrote:The problem was that there are a few large classes at the start of the hierarchy, and with the old version of ddox the function pages would not only be generated for the base class, but also for all the derived classes. So when you have a base class with 264 functions, and you have 385 classes that are directly or indirectly derived from it. Things start to add up, That is 101_640 html pages just for this one case, and there are more. Luckily this is fixed, especially because ddox never actually linked to these pages.One issue is the shear size of the generated documentation, though the current version of ddox no longer generates a ton of unused files bringing the size down from 15-20GB to a mere 2GB.what?! I'm not actually sure how much gtk alone takes, but my entire doc folder is 4 GB, including a good chunk of the dub repo, phobos, druntime, my stuff, search indexes, archives, etc. I guess it is possible the gtkd is 2 GB of that, but at least it isn't 20.That would be great.The need to go trough the empty module page when browsing the documentation. For a lot / most? functions the complete documentation is in the overview defeating the purpose of the one page per artifact.If you guys are interested, I can do a custom adrdox for gtk that: * reads more of the gtk syntax https://developer.gnome.org/gtk-doc-manual/stable/documenting_syntax.html.en * recognizes the one-item-per-module pattern and skips the empty pages * has a style more like https://gtkd.org/index.html * Maybe a few other little things?I don't use the documentation myself so this isn't really a problem. -- Mike WeyAnd im not a big fan of the one page per artifact style of documentation.Oh, it is so much better in a lot of ways.
Aug 10 2017
On Thursday, 10 August 2017 at 14:55:06 UTC, Mike Wey wrote:The problem was that there are a few large classes at the start of the hierarchy, and with the old version of ddox the function pages would not only be generated for the base class, but also for all the derived classes.Oh, I see. My generator lists them on the index, but doesn't recreate it each time, it just links. For example: http://dpldocs.info/experimental-docs/gtk.ApplicationWindow.ApplicationWindow.html it lists inherited members again, but not all their docs.That would be great.kewlI don't use the documentation myself so this isn't really a problem.It is a lot easier to link to individual pages from the outside which means search is more reliable, the back button works, stuff like that.
Aug 10 2017
On Thursday, 10 August 2017 at 14:59:52 UTC, Adam D. Ruppe wrote:On Thursday, 10 August 2017 at 14:55:06 UTC, Mike Wey wrote:Hi, The way valadoc.org exposes the docs makes them very easy to read and find things (at least for me). A. Corbi[...]Oh, I see. My generator lists them on the index, but doesn't recreate it each time, it just links. For example: http://dpldocs.info/experimental-docs/gtk.ApplicationWindow.ApplicationWindow.html it lists inherited members again, but not all their docs.[...]kewl[...]It is a lot easier to link to individual pages from the outside which means search is more reliable, the back button works, stuff like that.
Aug 11 2017