Release v0.9.4

[elementgreen]

Seems like a good time to do another release!

Remaining tasks I can think of:

• Update docs at https://gid.dpldocs.info/index.html (how to do this?)
• Update the giD README.md
  • Link to the docs and other relevant updates (versioned package names, optional params, rename updates, Mac support)
  • Remove C API doc links
  • Link to your examples project

I've done a little testing, just to make sure my own applications still compile and run as well as the gid-gtk4-examples, but additional testing would be great!

CC @dejlek

[dejlek]

I am going to ask @adamdruppe on IRC today how to refresh. It could be simply that when you make a new release, dpldocs.info will refresh automatically. Idk... Latest generated code by gidgen is amazing (with default parameter values)! Well-done! I am planning to add at least one tiny demo application to gid-examples for each package that is generated in giddy. Including the recently added Gtk3.

[adamdruppe]

if you go to the specific link for a version it will auto generate, or there's a hidden little "Clear cache" button on the bottom of a page that can trigger a rebuild. but probably don't do it yet, i can enable the gtk doc syntax rewrite before the next rebuild. busy day today but i should be able to get to it at some point.

[dejlek]

Not sure gtk doc syntax is necessary as gidgen is generating ddoc style docs. Thanks Adam!

[adamdruppe]

eh there's things it doesn't do like look here https://gid.dpldocs.info/gtk.widget.Widget.html

%GTK_SIZE_REQUEST_CONSTANT_SIZE

is one i know i translate but is still here

vfunc@Gtk.Widget.measure

i don't recall doing that so my translator will prolly leave it alone but it is a pretty easy translation to add

i think the converter here is trying to add some stuff like $(LPAREN) but that's inappropriate as seen in the code example (that might be necessary in ddoc, but remember, adrdox is not ddoc). the indentation looks off there too but i guess that's also true in the original (see the output of my translator for this same class, well maybe an older version but basically on gtkd here https://api.gtkd.org/gtk.Widget.Widget.html )

Also those ### things i think are meant to be markdown style headers but there's something lost in translation there (adrdox supports those but only if they're at the start of a line and have empty lines before and after, see http://dpldocs.info/experimental-docs/adrdox.syntax.html#headers )

the xml looks slightly wrong. Just a bunch of little bugs, we can fix on either end but it would be cool to fix them all.

So there's a number of bugs with both of them.

[elementgreen]

As you point out, there are still some issues with the generated ddoc output from gidgen. It does make an attempt to convert gtk-doc content to ddoc, but is lacking some conversions and sounds like it is making a mess of some other things, like the markdown stuff as you mentioned.

adrdox seems like the best documentation reference I have seen so far, so I will make gidgen conform to it. This syntax page looks really helpful for this. I did not know about this package until @dejlek sicced it on giD. It's quite nice! Can't tell you how many different ddoc documentation packages I tried and found to be inadequate. adrdox seems perfect so far. Bravo!

[dejlek]

Yep! I love dpldocs!

@adamdruppe keep in mind there there are now two different GTK subpackages in giD - gtk3 and gtk4. Both packages (dub packages) contain the same namespace, starting with the gtk package. So dpldocs (adrdox) may get confused there.

[adamdruppe]

yeah that could be trouble since adrdox assumes (which is required by the D language for libs used together!) that the module namespace is global.

i guess you can't use gtk3 and 4 together in the same application though.

[dejlek]

Yep, makes no sense. :) Same goes for vte3 (gtk4) vs vte2 (gtk3).

Question however is, which GTK package are seeing here: https://gid.dpldocs.info/gtk.html . GTK3 or GTK4, or BOTH (mixed modules from both gtk3 and gtk4)!??

[adamdruppe]

yeah idk it could be either or both, it indexes by module name so if there's duplicates one will be overwritten by the other. it could even be legitimately random as it breaks up the files into different threads.....

[elementgreen]

Is there any way to specify the dub sub package as part of the fully qualified symbol name? Kind of ugly, but it would look like gtk4.gtk.widget.Widget for example. One other potential way to handle this would be to utilize the package dependencies intelligently in some way. We opted not to have any version in the toplevel module directory, since as mentioned there shouldn't be the need to have both. I suppose that is one other way to handle this though, make the gtk4 package use gtk4.widget.Widget for example.

[adamdruppe]

the D language and dub know almost nothing about each other, so you can't pull the package name directly, but you could put module gtk4.gtk.widget; at the top when generating the files. similarly adrdox knows almost nothing about dub - all it knows is how to look up a repository download link from a dub package name, then downloads it and starts looking for D files inside. since the subpackages are all in the same repo, adrdox sees them all at once.

(when running adrdox from the command line yourself, you tell it a base directory and it reads the contents. so you could run it separately for each directory in there. a potential option here is to rig the dpldocs runner to special case your repo to do that too. though the dpldocs runner is supposed to be retired "soon" when the DLF finishes setting up their own thing so idk how long that would stay up. of course i could just keep your special case stuff there anyway.)

[elementgreen]

@dejlek Do you think it would be worth adding the version to the top-level module directory for this (gtk4 instead of gtk for example)? I'm leaning towards a "no" on this.

So that leaves modifying the doc generation. One solution I am thinking of, is that I could set up adrdox on my VPS and host the docs with whatever custom runner/doc modification logic we need to get things to work right with the multiple versions. I have some changes I'd like to make to the theme as well to make it a little more like the gtk-doc theme.

[elementgreen]

I just generated the docs locally on my own system. Was surprised how many files were produced (20K+) and almost 250MB. I fixed a number of issues in the DDoc output in gidgen, so now a lot more things are working correctly.

• Removed the '*' from each comment line.
• Now preserving white space, including blank lines, so headers (#) work.
• I removed the \$(LPAREN) and \$(RPAREN) nightmare and it seems to work OK with just regular parenthesis.
• Currently I'm just escaping '$' symbols with \$. I removed the escaping of '=', as I wasn't sure if that was required.
• I added cross references for %Symbol references, but it seems like there is an issue with adrdox and how gidgen currently generates enums. It creates an enum with the original GtkEnumName and then adds an alias to the local EnumName for D. I'm considering doing away with this extra alias, as I can't really see it being all that useful, which will probably fix this.

gidgen creates a much more complete binding and almost completely automated, compared to gtk-d. So I can see how even those who use Gtk3 would want to use giD. So my intention is to get the documentation working with multiple sub-package versions.

Would it be possible to run adrdox for each sub-package as you suggested and tell it which other sub-packages to load for cross referencing as it is currently? I could then handle this externally to adrdox, with respect to the dependencies. Just run it separately for each sub-package, specifying it's proper versioned dependency.

[adamdruppe]

adrdox does its own cross referencing, put the name in brackets and it figures out the link. it is even somewhat aware of scopes and imports and will try to work with them to resolve names. So enums can be given by just the full D name probably. If you want to load something for cross referencing but not generate its docs, use the --load= command line arg and there's a package-path which can change links (but this is D package, not dub package, so prefix on module name)

my blog for example does this command:

~/program/d-diff/doc2 --blog-mode --copy-standard-files=false -o /var/www/dpldocs.info/this-week-in-d/ --package-path='*=//opendlang.org/library/' --package-path='Blog.*=' --load . 2025*.d blog.d --load ~/arsd/ # -j 1

to output it all in my web dir, load the arsd libs for cross reference, then put most links to the opend website, but any module Blog.* will use no prefix; local link there.

and with adrdox inside backtick `thing` or either code block, either ddoc style --- or markdown style ```, don't use any ddoc syntax, no escaping or anything. other stuff maybe but adrdox tries to do the right thing most the time, it is $( the pair that gets treatment, and then it looks for balanced parens too, so only unbalanced parens need the LPAREN/RPAREN dance.

[elementgreen]

Indeed adrdox is working with cross references currently for functions, methods, and classes with the output from gidgen. It is the enum types and members that aren't working correctly. I am specifying them with their full D name, such as [gtk.types.Orientation.Vertical] but it ends up with a 404, since there is no gtk.types.Orientation page. It could be that the aliasing that I described above is confusing adrdox. Basically the enum is actually declared as enum GtkOrientation in a c.types module and then there is an alias in a D types module which looks like alias Orientation = GtkOrientation;. Other than that and the multi-version issue, I haven't seen any other problems. It is generating code examples, etc.

[adamdruppe]

does the e num have a doc comment on it? even an empty one will trigger generaiton, but none at all is not generated by default (tho there is the --document-undocumented switch for that, it can explode the already bloated generation even more)

///
enum Foo { } // this is linkable

enum Foo {} // this is not because no commment
```

[elementgreen]

The enum declarations do have comments, but the aliases do not. I will try adding blank comments to them to see if that helps.

[dejlek]

@elementgreen I must admit I did not have time to look closely at adrdox. I wonder whether we could simply add "doc" target to giddy Makefile, and make it go through all subpackages and generate docs... The only problem I can think of are cross-package links that we may lose this way (unless there is some way to instruct adrdox to inject correct links).

[adamdruppe]

ok nice, segfault is always iffy but im lazy so idk (so fun fact i wrote most of this stuff over the christmas break of 2016. i meant to eventually come back later and clean it up. eventually hasn't happened yet.)

but the index.html kinda sorta sucks anyway, you might consider just replacing that individual file with something else you make separately.

[elementgreen]

Sounds like a rather productive winter break! After my rather poor experience with other DDoc html generators, I had considered trying to write my own. Realized it was a rather daunting task though, so it is great to find adrdox! I think I should be able to get it to work, with the help of an external tool to execute it for each sub package with loaded dependencies.

[dejlek]

To be honest I am OK if gid.dpldocs.com or your website shows only latest version of the subpackages. If we can easily have that is will be absolutely fine at this stage. We can solve this later. So, I suggest for the doc generation we simply remove gtk3, gdk3, vte2, gtksource4 and build docs "the usual way". This will make sure we have GTK4-related docs in very useful state.

[elementgreen]

I thought I almost had things working with a helper utility I created to determine the recursive dependencies of each package and then run adrdox for each package with the approprate --load and --package-path commands. The package being generated has the correct external links, but if you start visiting other external packages, the links start breaking. Probably need to fix this properly in adrdox.

I agree that what you suggest is the best solution for now. I have the result of this at https://www.kymorphia.com/gid/. I have a couple more things I want to fix, then I'll push a bunch of commits for gidgen and gid. At that point I think the release will be ready.

[dejlek]

Brilliant! I think this is absolutely fine for now...

[elementgreen]

Looks like the changes to the enums has caused a cyclical module constructor dependency, since they are declared in the D types module which can depend on C types modules from other packages, which depend on D types modules, etc. Going to change it back to the way it was before. Perhaps adding proper /** */ blank DDoc comments before the aliases will make them appear in the adrdox output. I'm not sure if I tried that before (I may have been using the /// variety).

[elementgreen]

Just released v0.9.4 of gidgen and giD!

[dejlek]

Good job!
Though now vte and gtksource examples in gid-examples do not build... Must be something trivial...