www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - dub projects generate docs and host on code.dlang.org?

reply Manu via Digitalmars-d <digitalmars-d puremagic.com> writes:
I've seen a lot of dub projects with embedded ddoc that follows phobos
example.
These projects are then hosted on code.dlang.org, but often, the docs are
never generated and hosted anywhere.
In the event they are, links to docs are ad-hoc and unpredictable, and the
formatting/styling/etc is not standard/consistent.

Suggest; code.dlang.org should attempt to generate ddoc for each hosted
project, host it, and clearly link to it from the project front-page.
Hosted docs should be styled consistently (matching phobos?).

Thoughts?
- Manu
Sep 04 2017
next sibling parent reply Joakim <dlang joakim.fea.st> writes:
On Monday, 4 September 2017 at 10:47:47 UTC, Manu wrote:
 I've seen a lot of dub projects with embedded ddoc that follows 
 phobos
 example.
 These projects are then hosted on code.dlang.org, but often, 
 the docs are
 never generated and hosted anywhere.
 In the event they are, links to docs are ad-hoc and 
 unpredictable, and the
 formatting/styling/etc is not standard/consistent.

 Suggest; code.dlang.org should attempt to generate ddoc for 
 each hosted project, host it, and clearly link to it from the 
 project front-page. Hosted docs should be styled consistently 
 (matching phobos?).

 Thoughts?
 - Manu
While it's an interesting suggestion, dub has 355 open issues, would be better if more people pitched in on those: https://github.com/dlang/dub/issues
Sep 04 2017
next sibling parent reply Adam D. Ruppe <destructionator gmail.com> writes:
On Monday, 4 September 2017 at 11:15:08 UTC, Joakim wrote:
 While it's an interesting suggestion, dub has 355 open issues, 
 would be better if more people pitched in on those:
I have zero interest in fixing dub issues since I have zero interest in using dub. If one of the libraries were compelling... and I actually knew about it though, that equation may change. Making the code repository show documentation will do a lot to make the library more discoverable and valuable, which in turn, can drive dub use and bring with it more contributors. I think this is a good idea (and I bought a VM to set up to do it myself, but I went too cheap and the 512 MB of memory isn't enough to actually build the docs! ugh.)
Sep 04 2017
next sibling parent reply Manu via Digitalmars-d <digitalmars-d puremagic.com> writes:
On 5 September 2017 at 13:15, Adam D. Ruppe via Digitalmars-d <
digitalmars-d puremagic.com> wrote:

 On Monday, 4 September 2017 at 11:15:08 UTC, Joakim wrote:

 While it's an interesting suggestion, dub has 355 open issues, would be
 better if more people pitched in on those:
I have zero interest in fixing dub issues since I have zero interest in using dub. If one of the libraries were compelling... and I actually knew about it though, that equation may change. Making the code repository show documentation will do a lot to make the library more discoverable and valuable, which in turn, can drive dub use and bring with it more contributors.
This is exactly what I was thinking.
Sep 04 2017
parent Joakim <dlang joakim.fea.st> writes:
On Tuesday, 5 September 2017 at 03:47:12 UTC, Manu wrote:
 On 5 September 2017 at 13:15, Adam D. Ruppe via Digitalmars-d < 
 digitalmars-d puremagic.com> wrote:

 On Monday, 4 September 2017 at 11:15:08 UTC, Joakim wrote:

 While it's an interesting suggestion, dub has 355 open 
 issues, would be better if more people pitched in on those:
I have zero interest in fixing dub issues since I have zero interest in using dub. If one of the libraries were compelling... and I actually knew about it though, that equation may change. Making the code repository show documentation will do a lot to make the library more discoverable and valuable, which in turn, can drive dub use and bring with it more contributors.
This is exactly what I was thinking.
btw, there is a three-year-old open issue for this: https://github.com/dlang/dub/issues/355 The dub codebase isn't that big- DScanner reports 14.4 klocs- and Sonke's code is nicely formatted and easy to dive into. Everybody wants stuff in dmd, from bug fixes to new features, but doesn't necessarily have the compiler knowledge or bandwidth to decipher Walter's code. Dub, on the other hand, is something most everybody can understand, and PRs would benefit the entire community. It is still primarily a one-man show, despite Martin's efforts: https://github.com/dlang/dub/graphs/contributors I suggest everyone take a look at some of those issues, most are potential enhancements that anyone could add.
Sep 04 2017
prev sibling next sibling parent Joakim <dlang joakim.fea.st> writes:
On Tuesday, 5 September 2017 at 03:15:58 UTC, Adam D. Ruppe wrote:
 On Monday, 4 September 2017 at 11:15:08 UTC, Joakim wrote:
 While it's an interesting suggestion, dub has 355 open issues, 
 would be better if more people pitched in on those:
I have zero interest in fixing dub issues since I have zero interest in using dub.
I have not been using dub either, so I didn't know about all the open issues until now, when I started trying out dub on Android/ARM, where I will soon be shipping it with the ldc package for the Termux Android app.
 If one of the libraries were compelling... and I actually knew 
 about it though, that equation may change.

 Making the code repository show documentation will do a lot to 
 make the library more discoverable and valuable, which in turn, 
 can drive dub use and bring with it more contributors.
If the library authors wanted all that, they'd put up the docs themselves. But sure, doing it for them could help.
 I think this is a good idea (and I bought a VM to set up to do 
 it myself, but I went too cheap and the 512 MB of memory isn't 
 enough to actually build the docs! ugh.)
Great, I'd like to see more people chip in with the open issues though, like I have been recently with a few.
Sep 04 2017
prev sibling parent reply Laeeth Isharc <Laeeth kaleidic.io> writes:
On Tuesday, 5 September 2017 at 03:15:58 UTC, Adam D. Ruppe wrote:
 On Monday, 4 September 2017 at 11:15:08 UTC, Joakim wrote:
 While it's an interesting suggestion, dub has 355 open issues, 
 would be better if more people pitched in on those:
I have zero interest in fixing dub issues since I have zero interest in using dub. If one of the libraries were compelling... and I actually knew about it though, that equation may change. Making the code repository show documentation will do a lot to make the library more discoverable and valuable, which in turn, can drive dub use and bring with it more contributors. I think this is a good idea (and I bought a VM to set up to do it myself, but I went too cheap and the 512 MB of memory isn't enough to actually build the docs! ugh.)
If you want a larger VM email me specs and I will set one up for you. I guess the doc generation doesn't need much changing on dub. Maybe an extra command line option to build and publish docs that calls a field specified in dub.sdl like postgenerate command because you don't want to build docs every time and creating separate build configurations means you now have double the number, with and without docs. And custom command allows you to use a different doc generator. But we could have a default command to generate those for dub the repository. And then the template for the web site would just need to have a link to appropriate directory added? We have contributed to dub in past - John Colvin worked on this. One problem was lack of bandwidth to review pull requests. If we get better review and still don't have contributions then one can address that directly, but for now review seems the bottleneck.
Sep 05 2017
parent Adam D. Ruppe <destructionator gmail.com> writes:
On Tuesday, 5 September 2017 at 15:46:27 UTC, Laeeth Isharc wrote:
 If you want a larger VM email me specs and I will set one up 
 for you.
My doc generator can eat over 4 gigabytes... but for just minutes at a time, before going back to 16 megabytes to host plainly.... or 2 GB again to host with full server-side search. But I should be able to work with a fraction of that for the typical dub library... I'm just not sure what yet. And I might be able to optimize that a lot (I just run it at home for my own use with a whopping 16 GB, so I'm in no rush... I just don't want to run arbitrary crap from home off dub)
 I guess the doc generation doesn't need much changing on dub.  
 Maybe an extra command line option to build and publish docs
If it has to be configured, it isn't going to be used. I want it automatic.
Sep 06 2017
prev sibling parent reply dhasenan <dhasenan gmail.com> writes:
On Monday, 4 September 2017 at 11:15:08 UTC, Joakim wrote:
 While it's an interesting suggestion, dub has 355 open issues, 
 would be better if more people pitched in on those:

 https://github.com/dlang/dub/issues
It looks like the current policy is to leave issues open unless they're exact duplicates or have a pull request that mentions fixing them. (Not quite so dour, but it's not great.) That artificially inflates the count with stuff like: * There's already a way to do that, but it doesn't match what you want * We don't have anything that matches, but we're not going to add it without a large swell of requests * Reported crash / error / etc from four years ago that was probably fixed three years ago * Issue was fixed but the pull request didn't reference the issue I'm quite willing to do bug triage, but I don't have the authority.
Sep 12 2017
next sibling parent Seb <seb wilzba.ch> writes:
On Tuesday, 12 September 2017 at 18:42:35 UTC, dhasenan wrote:
 On Monday, 4 September 2017 at 11:15:08 UTC, Joakim wrote:
 I'm quite willing to do bug triage, but I don't have the 
 authority.
That's great! Simply start going through the issues and comment when you think it should be closed. This will do fine for the beginning and most likely we can even give you the needed permissions ;-)
Sep 12 2017
prev sibling parent Joakim <dlang joakim.fea.st> writes:
On Tuesday, 12 September 2017 at 18:42:35 UTC, dhasenan wrote:
 On Monday, 4 September 2017 at 11:15:08 UTC, Joakim wrote:
 While it's an interesting suggestion, dub has 355 open issues, 
 would be better if more people pitched in on those:

 https://github.com/dlang/dub/issues
It looks like the current policy is to leave issues open unless they're exact duplicates or have a pull request that mentions fixing them. (Not quite so dour, but it's not great.) That artificially inflates the count with stuff like: * There's already a way to do that, but it doesn't match what you want * We don't have anything that matches, but we're not going to add it without a large swell of requests * Reported crash / error / etc from four years ago that was probably fixed three years ago * Issue was fixed but the pull request didn't reference the issue I'm quite willing to do bug triage, but I don't have the authority.
Yeah, Sonke is very liberal about leaving issues open and a tool like this has a lot of features people want, so it isn't as bad as it looks. I went through many of the issues and got Seb to close 5-6 of them, and then was made a member of the dlang/dub team. Just comment with one of our nicks on any issue and we'll do what's needed.
Sep 12 2017
prev sibling next sibling parent reply user1234 <user1234 12.hu> writes:
On Monday, 4 September 2017 at 10:47:47 UTC, Manu wrote:
 I've seen a lot of dub projects with embedded ddoc that follows 
 phobos
 example.
 These projects are then hosted on code.dlang.org, but often, 
 the docs are
 never generated and hosted anywhere.
 In the event they are, links to docs are ad-hoc and 
 unpredictable, and the
 formatting/styling/etc is not standard/consistent.

 Suggest; code.dlang.org should attempt to generate ddoc for 
 each hosted project, host it, and clearly link to it from the 
 project front-page. Hosted docs should be styled consistently 
 (matching phobos?).

 Thoughts?
 - Manu
It has existed in the past, see http://forum.dlang.org/thread/weuxppabkrreaxbqqpdv forum.dlang.org?page=1
Sep 04 2017
parent reply Manu via Digitalmars-d <digitalmars-d puremagic.com> writes:
On 4 September 2017 at 21:45, user1234 via Digitalmars-d <
digitalmars-d puremagic.com> wrote:

 On Monday, 4 September 2017 at 10:47:47 UTC, Manu wrote:

 I've seen a lot of dub projects with embedded ddoc that follows phobos
 example.
 These projects are then hosted on code.dlang.org, but often, the docs are
 never generated and hosted anywhere.
 In the event they are, links to docs are ad-hoc and unpredictable, and the
 formatting/styling/etc is not standard/consistent.

 Suggest; code.dlang.org should attempt to generate ddoc for each hosted
 project, host it, and clearly link to it from the project front-page.
 Hosted docs should be styled consistently (matching phobos?).

 Thoughts?
 - Manu
It has existed in the past, see http://forum.dlang.org/thread/ weuxppabkrreaxbqqpdv forum.dlang.org?page=1
Seems to be gone. If people think this is sensible, I'd go as far as saying this would be a major ecosystem usability improvement, and maybe even worthy of paid attention... (Andrei?)
Sep 04 2017
parent reply user1234 <user1234 12.hu> writes:
On Tuesday, 5 September 2017 at 02:08:08 UTC, Manu wrote:
 On 4 September 2017 at 21:45, user1234 via Digitalmars-d < 
 digitalmars-d puremagic.com> wrote:

 On Monday, 4 September 2017 at 10:47:47 UTC, Manu wrote:

 Thoughts?
 - Manu
It has existed in the past, see http://forum.dlang.org/thread/ weuxppabkrreaxbqqpdv forum.dlang.org?page=1
Seems to be gone.
Yes of course it's gone. That's a fact. I wanted to bring this fact in the discussion. That has existed already. I think nobody cared about the initiative.
Sep 05 2017
parent colin <grogan.colin gmail.com> writes:
On Tuesday, 5 September 2017 at 22:30:24 UTC, user1234 wrote:
 On Tuesday, 5 September 2017 at 02:08:08 UTC, Manu wrote:
 On 4 September 2017 at 21:45, user1234 via Digitalmars-d < 
 digitalmars-d puremagic.com> wrote:

 On Monday, 4 September 2017 at 10:47:47 UTC, Manu wrote:

 Thoughts?
 - Manu
It has existed in the past, see http://forum.dlang.org/thread/ weuxppabkrreaxbqqpdv forum.dlang.org?page=1
Seems to be gone.
Yes of course it's gone. That's a fact. I wanted to bring this fact in the discussion. That has existed already. I think nobody cared about the initiative.
I think it was nice. It just wasn't particularly well integrated and it's look and feel was... off. This thread proves theres interest in this, so it would certainly be worth some time. Maybe reviving kiith-sa's work or starting a new?
Sep 06 2017
prev sibling next sibling parent Jacob Carlborg <doob me.com> writes:
On 2017-09-04 12:47, Manu via Digitalmars-d wrote:
 I've seen a lot of dub projects with embedded ddoc that follows phobos 
 example.
 These projects are then hosted on code.dlang.org 
 <http://code.dlang.org>, but often, the docs are never generated and 
 hosted anywhere.
 In the event they are, links to docs are ad-hoc and unpredictable, and 
 the formatting/styling/etc is not standard/consistent.
 
 Suggest; code.dlang.org <http://code.dlang.org> should attempt to 
 generate ddoc for each hosted project, host it, and clearly link to it 
 from the project front-page.
 Hosted docs should be styled consistently (matching phobos?).
 
 Thoughts?
Yes please :) -- /Jacob Carlborg
Sep 04 2017
prev sibling next sibling parent Andrea Fontana <nospam example.com> writes:
On Monday, 4 September 2017 at 10:47:47 UTC, Manu wrote:
 I've seen a lot of dub projects with embedded ddoc that follows 
 phobos
 example.
 These projects are then hosted on code.dlang.org, but often, 
 the docs are
 never generated and hosted anywhere.
 In the event they are, links to docs are ad-hoc and 
 unpredictable, and the
 formatting/styling/etc is not standard/consistent.

 Suggest; code.dlang.org should attempt to generate ddoc for 
 each hosted project, host it, and clearly link to it from the 
 project front-page. Hosted docs should be styled consistently 
 (matching phobos?).

 Thoughts?
 - Manu
+1
Sep 04 2017
prev sibling next sibling parent reply Nicholas Wilson <iamthewilsonator hotmail.com> writes:
On Monday, 4 September 2017 at 10:47:47 UTC, Manu wrote:
 I've seen a lot of dub projects with embedded ddoc that follows 
 phobos
 example.
 These projects are then hosted on code.dlang.org, but often, 
 the docs are
 never generated and hosted anywhere.
 In the event they are, links to docs are ad-hoc and 
 unpredictable, and the
 formatting/styling/etc is not standard/consistent.

 Suggest; code.dlang.org should attempt to generate ddoc for 
 each hosted project, host it, and clearly link to it from the 
 project front-page. Hosted docs should be styled consistently 
 (matching phobos?).

 Thoughts?
 - Manu
Mir uses http://docs.algorithm.dlang.io/latest/index.html for its docs. Perhaps something like it could be extended for other projects? I think Sebastian Wilzbach would be the person to contact about this.
Sep 04 2017
next sibling parent jmh530 <john.michael.hall gmail.com> writes:
On Tuesday, 5 September 2017 at 02:21:26 UTC, Nicholas Wilson 
wrote:
 Mir uses http://docs.algorithm.dlang.io/latest/index.html for 
 its docs. Perhaps something like it could be extended for other 
 projects?
 I think Sebastian Wilzbach would be the person to contact about 
 this.
However it is that it works, I've always liked the look of mir's documentation pages.
Sep 04 2017
prev sibling parent Seb <seb wilzba.ch> writes:
On Tuesday, 5 September 2017 at 02:21:26 UTC, Nicholas Wilson 
wrote:
 On Monday, 4 September 2017 at 10:47:47 UTC, Manu wrote:
 I've seen a lot of dub projects with embedded ddoc that 
 follows phobos
 example.
 These projects are then hosted on code.dlang.org, but often, 
 the docs are
 never generated and hosted anywhere.
 In the event they are, links to docs are ad-hoc and 
 unpredictable, and the
 formatting/styling/etc is not standard/consistent.

 Suggest; code.dlang.org should attempt to generate ddoc for 
 each hosted project, host it, and clearly link to it from the 
 project front-page. Hosted docs should be styled consistently 
 (matching phobos?).

 Thoughts?
 - Manu
Mir uses http://docs.algorithm.dlang.io/latest/index.html for its docs. Perhaps something like it could be extended for other projects? I think Sebastian Wilzbach would be the person to contact about this.
Unfortunately the setup for Mir's repositories is quite complicated as it's based on Ddoc and dlang.org. I think a better approach would be to use adrdox or Ddox with the scod theme [1]. [1] https://github.com/MartinNowak/scod
Sep 05 2017
prev sibling next sibling parent Vadim Lopatin <coolreader.org gmail.com> writes:
On Monday, 4 September 2017 at 10:47:47 UTC, Manu wrote:
 I've seen a lot of dub projects with embedded ddoc that follows 
 phobos
 example.
 These projects are then hosted on code.dlang.org, but often, 
 the docs are
 never generated and hosted anywhere.
 In the event they are, links to docs are ad-hoc and 
 unpredictable, and the
 formatting/styling/etc is not standard/consistent.

 Suggest; code.dlang.org should attempt to generate ddoc for 
 each hosted project, host it, and clearly link to it from the 
 project front-page. Hosted docs should be styled consistently 
 (matching phobos?).

 Thoughts?
 - Manu
It would be really useful feature!
Sep 04 2017
prev sibling next sibling parent reply denizzzka <4d.eniz.zz gmail.com> writes:
On Monday, 4 September 2017 at 10:47:47 UTC, Manu wrote:
 Suggest; code.dlang.org should attempt to generate ddoc for 
 each hosted project, host it, and clearly link to it from the 
 project front-page. Hosted docs should be styled consistently 
 (matching phobos?).

 Thoughts?
 - Manu
It would be nice if the DUB will be able to generate "docsets" for offline documentation browsers: https://kapeli.com/dash (can be integrated into various IDEs!) https://zealdocs.org/ http://devdocs.io/
Sep 05 2017
parent reply Seb <seb wilzba.ch> writes:
On Tuesday, 5 September 2017 at 07:59:09 UTC, denizzzka wrote:
 On Monday, 4 September 2017 at 10:47:47 UTC, Manu wrote:
 Suggest; code.dlang.org should attempt to generate ddoc for 
 each hosted project, host it, and clearly link to it from the 
 project front-page. Hosted docs should be styled consistently 
 (matching phobos?).

 Thoughts?
 - Manu
It would be nice if the DUB will be able to generate "docsets" for offline documentation browsers: https://kapeli.com/dash (can be integrated into various IDEs!) https://zealdocs.org/ http://devdocs.io/
This has been merged this week: http://devdocs.io/d/
Sep 05 2017
parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 09/05/2017 12:05 PM, Seb wrote:
 On Tuesday, 5 September 2017 at 07:59:09 UTC, denizzzka wrote:
 On Monday, 4 September 2017 at 10:47:47 UTC, Manu wrote:
 Suggest; code.dlang.org should attempt to generate ddoc for each 
 hosted project, host it, and clearly link to it from the project 
 front-page. Hosted docs should be styled consistently (matching 
 phobos?).

 Thoughts?
 - Manu
It would be nice if the DUB will be able to generate "docsets" for offline documentation browsers: https://kapeli.com/dash (can be integrated into various IDEs!) https://zealdocs.org/ http://devdocs.io/
This has been merged this week: http://devdocs.io/d/
Nice! Who did the work? -- Andrei
Sep 05 2017
parent Steven Schveighoffer <schveiguy yahoo.com> writes:
On 9/5/17 5:46 PM, Andrei Alexandrescu wrote:
 On 09/05/2017 12:05 PM, Seb wrote:
 On Tuesday, 5 September 2017 at 07:59:09 UTC, denizzzka wrote:
 On Monday, 4 September 2017 at 10:47:47 UTC, Manu wrote:
 Suggest; code.dlang.org should attempt to generate ddoc for each 
 hosted project, host it, and clearly link to it from the project 
 front-page. Hosted docs should be styled consistently (matching 
 phobos?).

 Thoughts?
 - Manu
It would be nice if the DUB will be able to generate "docsets" for offline documentation browsers: https://kapeli.com/dash (can be integrated into various IDEs!) https://zealdocs.org/ http://devdocs.io/
This has been merged this week: http://devdocs.io/d/
Nice! Who did the work? -- Andrei
https://github.com/Thibaut/devdocs/pull/661 Looks great! -Steve
Sep 11 2017
prev sibling parent reply Vadim Lopatin <coolreader.org gmail.com> writes:
On Monday, 4 September 2017 at 10:47:47 UTC, Manu wrote:
 I've seen a lot of dub projects with embedded ddoc that follows 
 phobos
 example.
 These projects are then hosted on code.dlang.org, but often, 
 the docs are
 never generated and hosted anywhere.
 In the event they are, links to docs are ad-hoc and 
 unpredictable, and the
 formatting/styling/etc is not standard/consistent.

 Suggest; code.dlang.org should attempt to generate ddoc for 
 each hosted project, host it, and clearly link to it from the 
 project front-page. Hosted docs should be styled consistently 
 (matching phobos?).
Having automatically updated docs hosted on code.dlang.org will motivate package developers to write better ddoc comments for their code. It will get library packages more usable, and attract more users.
Sep 06 2017
parent reply Adam D. Ruppe <destructionator gmail.com> writes:
On Wednesday, 6 September 2017 at 14:04:56 UTC, Vadim Lopatin 
wrote:
 Having automatically updated docs hosted on code.dlang.org will 
 motivate package developers to write better ddoc comments for 
 their code.
I would go so far as to automatically downvote things with poor docs...
Sep 06 2017
parent Manu via Digitalmars-d <digitalmars-d puremagic.com> writes:
On 7 September 2017 at 00:17, Adam D. Ruppe via Digitalmars-d <
digitalmars-d puremagic.com> wrote:

 On Wednesday, 6 September 2017 at 14:04:56 UTC, Vadim Lopatin wrote:

 Having automatically updated docs hosted on code.dlang.org will motivate
 package developers to write better ddoc comments for their code.
I would go so far as to automatically downvote things with poor docs...
+1
Sep 08 2017