Re: Fix gtkD api display
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: [...] 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. Hi, The way valadoc.org exposes the docs makes them very easy to read and find things (at least for me). A. Corbi
Re: Fix gtkD api display
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. kewl I 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.
Re: Fix gtkD api display
On 10-08-17 15:57, Adam D. Ruppe wrote: 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 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. 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? That would be great. 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. I don't use the documentation myself so this isn't really a problem. -- Mike Wey
Re: Fix gtkD api display
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.
Re: Fix gtkD api display
On 04-08-17 17:24, Gerald wrote: 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. 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 Wey
Re: Fix gtkD api display
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: 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. 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. 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
Re: Fix gtkD api display
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: On Friday, 4 August 2017 at 15:08:27 UTC, Mike Wey wrote: [...] 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. Is there any online demo of it working? Unfortunately there is not, I just run it locally on my laptop.
Re: Fix gtkD api display
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.
Re: Fix gtkD api display
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: 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. Is there any online demo of it working? Thanks.
Re: Fix gtkD api display
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: https://api.gtkd.org/gtkd/gtk/ApplicationWindow.html So 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. 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.
Re: Fix gtkD api display
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.
Re: Fix gtkD api display
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
Re: Fix gtkD api display
On Friday, 4 August 2017 at 02:08:31 UTC, Johnson Jones wrote: https://api.gtkd.org/gtkd/gtk/ApplicationWindow.html So 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.
Re: Fix gtkD api display
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
Fix gtkD api display
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 ;)
