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