Make ddox the default doc for dlang.org menu

[wilzbach]

Starting with step 1 as outlined here

1. /library/ is promoted as the primary Phobos documentation in the site navigation.
2. /phobos/ is removed from search indexing.
3. /phobos/ is removed from site navigation.
4. /phobos/ is removed.

CC @s-ludwig

However I would love to love see the Disqus problem sorted out before. So let me summarize the three main options proposed so far:

Option 1: self-hosted commenting

I share a similar opinion as @MartinNowak:

I'd want to disable or replace discourse before we make it our official documentation. We could easily self-host some commenting functionality if deemed necessary, but adding an unmaintained communication channel isn't the best idea IMO.

Option 2: use DFeed

(from @CyberShadow)

I think it wouldn't be too hard to embed DFeed as a comment system. What do you think? Then anyone can subscribe to new comments through the usual means. The same solution can be applied to the blog. I understand that the current bottleneck is someone adding new groups to the NNTP server. Can that be resolved?

Option 3: remove Disqus

Yeah, I'm not likely to ever use disqus but if it went through the same n.g./mailing list interface at least I'd consider talking at times (though I personally think comments in documentation should typically be used to just go back and improve the documentation rather than making readers actually wade through the out-of-date and repetitive comment thread...)

Note that removing Disqus has been attempted this summer, which was reverted as @MartinNowak wasn't available at this time.

[andralex]

@wilzbach are examples runnable just the same in both? any dead links? anything to worry about? In the past I ran quickly into some issue.

[andralex]

e.g. https://dlang.org/library-prerelease/ has a few oddities:

• Table has a wide first column due to large module names such as std.experimental.allocator.building_blocks.affix_allocator. I think we could insert a soft break before each dot in these names? What's HTML for soft break - i.e. like ­ but without outputting a hyphen?
• Those std.experimental.allocator.building_blocks.* don't have any description
• Description for some modules comes in heading font, e.g. "Assembling Your Own Allocator"
• The table "Access to plattform libraries is supported by specific D header files" is odd because it has a bunch under C99 and nothing everywhere else
• The table "Deprecated D header files." has only one "C" in it?

[andralex]

I also don't see any runnable test. Do we need to do some deployment? @CyberShadow is ddox part of the auto-deployment engine?

[wilzbach]

I also don't see any runnable test. Do we need to do some deployment? @CyberShadow is ddox part of the auto-deployment engine?

I haven't found time to work on this yet. It's a different setup.

are examples runnable just the same in both?

Well there are different two setups (since two years) :/

any dead links? anything to worry about?

Ddoc will stay for quite a while.

In the past I ran quickly into some issue.

Yep I just started the discussion to figure out the last blocking points...

[wilzbach]

@wilzbach are examples runnable just the same in both?

They should be soon: https://github.com/dlang/dlang.org/pull/1532

[CyberShadow]

@CyberShadow is ddox part of the auto-deployment engine?

Yes. Runnable tests are just not implemented for DDox right now.

[wilzbach]

So what is the decision here?

• Support to run the tests with the ddox build has been added with https://github.com/dlang/dlang.org/pull/1532

• Do I understand it correctly that once the last glitches in ddox that Andrei has mentioned have been fixed, we can start the switch over?

• What is our consensus regarding Disqus / comment system? (@CyberShadow I think your opinion has a lot of weight here)

[andralex]

Copying from my older comments: "...e.g. https://dlang.org/library-prerelease/ has a few oddities: ..."

• Table has a wide first column due to large module names such as std.experimental.allocator.building_blocks.affix_allocator. I think we could insert a soft break before each dot in these names? What's HTML for soft break - i.e. like ­ but without outputting a hyphen?

Not fixed.

• Those std.experimental.allocator.building_blocks.* don't have any description

Not fixed.

• Description for some modules comes in heading font, e.g. "Assembling Your Own Allocator"

Not fixed.

• The table "Access to plattform libraries is supported by specific D header files" is odd because it has a bunch under C99 and nothing everywhere else

Not fixed.

• The table "Deprecated D header files." has only one "C" in it?

Not fixed.

[andralex]

I'd say let disqus be. Doesn't hurt and the dearth of comments is not a reflection on disqus as much as a lack of critical mass in viewership.

[adamdruppe]

On Wed, Feb 22, 2017 at 09:34:44AM -0800, Andrei Alexandrescu wrote:

• Those std.experimental.allocator.building_blocks.* don't have any description

That's not ddox's fault, the source for those submodules is missing documentation on the module declaration. We should do a Phobos PR to add some description text to those modules.

• Description for some modules comes in heading font, e.g. "Assembling Your Own Allocator"

dpldocs.info stripped the header tags there, but it is arguably also the source module's fault - it should have a brief summary before the headers and details.

• The table "Access to plattform libraries is supported by specific D header files" is odd because it has a bunch under C99 and nothing everywhere else

Again, those aren't documented in the source. We should do a druntime PR to add doc comments there. Or something. I'm not sure it makes sense to do too much ddoc of C declarations, but it is a FAQ "why isn't this documented on dlang.org?" so we should do SOMETHING.

So bottom line, let's do PRs on phobos and druntime to document these, and ddox should automatically pick up the benefit - and ddoc might too.

[andralex]

We should do a Phobos PR to add some description text to those modules.

Correct, those should ideally predate switching to ddox.

[adamdruppe]

I see very little value in giving every function its own page.

It helps so, so, so much on search results, and having plenty of space means it is possible to format the information better (ddox does meh on it but still). Consider that so many search engine hits go to ddox already, it just highlights how much easier they are to link to.

[andralex]

This goes on to confirm what I like to joke about: whatever we do, someone will be against it. Page-per-artifact has been vociferously asked for by many folks. Growing pains! My approach in this: we can afford to offer both with ease, so we should. (We're not alone; see e.g. https://www.gnu.org/software/make/manual/ which offers several ways to view the same documentation.)

[JackStouffer]

As long as /phobos/ is still available, then I'm fine with the ddox version. However, I still think it's not good enough for the default.

[CyberShadow]

https://dlang.org/library/std/range/drop.html shows raw HTML

[s-ludwig]

The source looks off: https://github.com/dlang/phobos/blob/v2.074.1/std/range/package.d#L2880 Embedding DDOC within backticks is "strange" and the opening back tick has no closing match.

[CyberShadow]

Thanks. https://github.com/dlang/phobos/pull/5494

[CyberShadow]

@s-ludwig Would it be possible to make DDox throw a hard error upon encountering such invalid syntax?

[s-ludwig]

@CyberShadow I'll remember to add that (https://github.com/rejectedsoftware/ddox/issues/154). I'd suggest to make this an opt-in switch, though, because it could break existing projects otherwise.

[CyberShadow]

Cheers. I guess we could grep the output in the makefile as well.

[CyberShadow]

I don't see any relevant warnings in dpl-docs output when running make -f posix.mak apidocs-prerelease, just some "Error parsing type" which seem unrelated. Perhaps there is no code to detect/warn on such malformed DDoc syntax yet?

[s-ludwig]

Indeed.. it currently silently uses the end of the paragraph to mark the end of the back tick code in this case.

[adamdruppe]

On Sun, Jun 18, 2017 at 01:13:37AM -0700, Sönke Ludwig wrote:

Embedding DDOC within backticks is "strange" and the opening back tick has no closing match.

If it has no closing match on the line, the backtick is supposed to be output literally. The backtick code thing is not supposed to be able to span lines.

I did that quite deliberately in the implementation for dmd because 1) linker output often does something like identifier `foo' and I wanted that to be copy/pastable and 2) github ignores it with no match too.

See the explicit comment here:

https://github.com/dlang/dmd/blob/master/src/ddmd/doc.d#L2166

[s-ludwig]

@adamdruppe: Fixed for DDOX 0.16.1: https://github.com/rejectedsoftware/ddox/issues/155

[adamdruppe]

On Sun, Jun 18, 2017 at 09:16:21AM -0700, Sönke Ludwig wrote:

@adamdruppe: Fixed for DDOX 0.16.1: https://github.com/rejectedsoftware/ddox/issues/155

Excellent!

[CyberShadow]

Some broken documentation (example) here:

https://dlang.org/library/std/algorithm/searching/find_skip.html

Looks OK on DDoc:

https://dlang.org/phobos/std_algorithm_searching.html#findSkip

[s-ludwig]

This is an effect of the necessary workaround to extract the unit test code for the example. I've opened a ticket (https://github.com/rejectedsoftware/ddox/issues/156) and this should be solvable by employing dparse to tokenize the source code instead of blindly searching for the last closing brace.

[CyberShadow]

The prototype here is really broken:

http://dlang.org/library-prerelease/std/file/dir_entries.html

Screenshot:

• The first line seems to be justified, making the sole two terms appear on the opposite sides of the box.
• The second line has no whitespace or word wrap points, making it go out of bounds.
• There is something wrong with the emitted data, the prototype itself doesn't even look like D code.

On Chrome the justification will not be visible as we do not enable it for that browser (because it does not support automatic hyphenation).

[andralex]

Only regular flowing text should be justified, nothing else (not even tables) btw.

[CyberShadow]

Yeah, I guess problems with justification slip through the cracks because it's disabled for Chrome (because of hyphenation), and many contributors test with it exclusively.