On Wednesday, 1 March 2017 at 20:10:35 UTC, Adam D. Ruppe wrote:
> On Wednesday, 1 March 2017 at 12:05:33 UTC, bachmeier wrote:
>> If by "surrender", you mean adopt your system for the official documentation, well I sure hope not. That's a fast way to kill progress on anything related to this language.
>
> Yeah, I'd prolly have to continue working on it myself but they could fork off a stable version to use on the website.
>
> Regardless though, I'd also be happy if the competitive pressure leads to improvements on the main site (while I continue to be streets ahead on my own site).

Hehe, well for those who haven't been following closely. Jack and I are putting some effort into improving the "official" documentation:

https://github.com/dlang/phobos/pulls?utf8=%E2%9C%93&q=is%3Apr%20label%3Adocumentation%20

Most of these changes are independent from Ddoc/Ddox/Adrdox/..., so everyone should be able to enjoy cleaner documentation soon.

@Adam: I like your docs as well!
Have you ever considered adding vibe.d to them?

On Wednesday, 1 March 2017 at 06:19:30 UTC, lobo wrote:
> On Wednesday, 1 March 2017 at 05:18:59 UTC, Adam D. Ruppe wrote:
>> I stumbled across std.typecons.Unique in my doc website today and realized there was a postblit in the source, but I didn't display the documentation comment.
>>
>> [...]
>
> Is it possible to use your tool to generate the docs for my own code?
>
> Thanks,
> lobo

Thanks, I'll give it a try.

lobo

On Wednesday, 1 March 2017 at 23:21:14 UTC, Seb wrote:
> https://github.com/dlang/phobos/pulls?utf8=%E2%9C%93&q=is%3Apr%20label%3Adocumentation%20
>
> Most of these changes are independent from Ddoc/Ddox/Adrdox/..., so everyone should be able to enjoy cleaner documentation soon.

Actually, almost none of that affects me! (Except perhaps causing more merge conflicts for me when I pull, alas, but that's the downside of doing a fork. I already killed most the LUCKY links, for example, and the booktables are redundant (though basically harmless) with my automatically generated listings.

My diff from upstream is now over 5300 lines long, including a mix of formatting, syntax, linking, and some content changes...

> @Adam: I like your docs as well!
> Have you ever considered adding vibe.d to them?

Once I'm happy with it, I might scrape code.dlang.org and pull it.

Though it is important to note that adrdox does NOT support user-defined ddoc macros, so not everything with ddoc will just work. I hardcoded a bunch of the common Phobos ones, but my goal ideally is to eliminate most macros in favor of things taking care of themselves with lightweight syntax (which ironically, was part of ddoc's original charter!)

On Thursday, 2 March 2017 at 00:06:17 UTC, Adam D. Ruppe wrote:
> Though it is important to note that adrdox does NOT support user-defined ddoc macros

But, it DOES now support a footnote kind of thing. Behold:

http://dpldocs.info/experimental-docs/test.html#footnotes

In ddoc, I was tempted to define a $(RANGE_CONCEPT Input) macro or something like that, which would expand do $(REF std,range,primitives,is$1Range, $1 range) or something along those lines (of course, ddoc is so underpowered that wouldn't even be that good..) because right now we repeat those references a LOT.

(Actually, I don't love linking to isInputRange's function definition. I'd prefer a higher-level overview of ranges when we link it, but isInputRange is the best we have written right now outside our various books.)

adrdox makes it a bit nicer, `[isInputRange|input range]` will do what's needed, as long as `std.range.primitives` is imported in scope (which it typically is for the constraint anyway), but what if we write a new conceptual article and want to change the links?

That's what led me to the Link_References idea. By defining:

concept_input_range = [isInputRange|input range]

we can just reference text like `It must be an [concept_input_range]` and be a bit more DRY (and btw concept_input_range is easier on my autocomplete algorithms than isInputRange|input range... and infinitely better than the ddoc macro mess.)

So, I went ahead and implemented that today. And footnotes, images, and popup text is easy to do in the same framework and sometimes useful too, so I just did it all together.


My generator isn't just about reading more semantics out of D, it is also about making something easier to use than ddoc.

On Wednesday, 1 March 2017 at 23:21:14 UTC, Seb wrote:
> @Adam: I like your docs as well!
> Have you ever considered adding vibe.d to them?

I just ran the generator over them now (though I did NOT add them to the search index or the source listing so you can't search or view source, but you can navigate):

http://dpldocs.info/experimental-docs/vibe.html

The generator did a decent job handling it, though some interlinking came out wonky, I'll have to look into that... but still, take a look.

As you might expect, I like mine better than the official site, even with my minor bugs. Take a look at this, for example:

http://vibed.org/api/vibe.http.server/HTTPServerOption

vs

http://dpldocs.info/experimental-docs/vibe.http.server.HTTPServerOption.html

I just find mine so much easier on the eyes. My nav is also far easier than the ddox one IMO. My sidebar only shows siblings and parents of the current decl, keeping it a flat list. It is less stuff instantly there, but it is so easy to click the parent that I don't get lost on mine and often do in the JS collapsible tree.