www.digitalmars.com         C & C++   DMDScript  

digitalmars.D.announce - The dub documentation is now on dub.pm

reply Seb <seb wilzba.ch> writes:
tl;dr: The dub documentation got split from the dub-registry 
repository and now lives on https://dub.pm 
(https://github.com/dlang/dub-docs).

Motivation:
-----------

- makes building the dub-registry faster
- people hosting a mirror or a private instance don't need to 
host the documentation too
- allows us to use a separate, more modern design for the dub 
docs (proposals are welcome!)
- makes it easier for people contributing the docs (less code and 
dependencies to build)
- allows us to remove the menu header at code.dlang.org and 
replace it with a nice, modern searchbar
- makes the deployment for the documentation easier (they are 
static
HTML after all) and we have already setup continuous deployment 
for the documentation (via Netlify)

As always, ideas and PRs to make DUB's documentation better are 
welcome.

PS: Of course all old documentation links will redirect to dub.pm
Jul 19 2018
parent reply Martin Tschierschke <mt smartdolphin.de> writes:
On Thursday, 19 July 2018 at 09:39:04 UTC, Seb wrote:

 tl;dr: The dub documentation got split from the dub-registry 
 repository and now lives on https://dub.pm 
 (https://github.com/dlang/dub-docs).

 Motivation:
 -----------

 - makes building the dub-registry faster
 - people hosting a mirror or a private instance don't need to 
 host the documentation too
 - allows us to use a separate, more modern design for the dub 
 docs (proposals are welcome!)
 - makes it easier for people contributing the docs (less code 
 and dependencies to build)
 - allows us to remove the menu header at code.dlang.org and 
 replace it with a nice, modern search bar
 - makes the deployment for the documentation easier (they are 
 static
 HTML after all) and we have already setup continuous deployment 
 for the documentation (via Netlify)

 As always, ideas and PRs to make DUB's documentation better are 
 welcome.

 PS: Of course all old documentation links will redirect to 
 dub.pm


Very ++ :-)

There should be a big section for well done dub.sdl / dub.json 
examples.

What about defining "comment" as an special keyword for the .json 
parser inside Dub
(just ignoring the content") to allow some kind comments inside 
.json
In the moment only dub.sdl may be more descriptive with #comments.
But many people prefer .json  where no comments are build in.

So allow to write "comment" : "This string will will be parsed 
away",
  may do the difference?

Best regards mt.
Jul 19 2018
next sibling parent aliak <something something.com> writes:
On Thursday, 19 July 2018 at 13:10:01 UTC, Martin Tschierschke 
wrote:

 On Thursday, 19 July 2018 at 09:39:04 UTC, Seb wrote:

 [...]


 Very ++ :-)

 There should be a big section for well done dub.sdl / dub.json 
 examples.

 What about defining "comment" as an special keyword for the 
 .json parser inside Dub
 (just ignoring the content") to allow some kind comments inside 
 .json
 In the moment only dub.sdl may be more descriptive with 
 #comments.
 But many people prefer .json  where no comments are build in.

 So allow to write "comment" : "This string will will be parsed 
 away",
  may do the difference?

 Best regards mt.


Yes! Examples would be awesome. I have a little thing going [1] 
that maybe is usable as a start or something?

[1] https://github.com/aliak00/dub-subpackages

Cheers,
  - Ali
Jul 19 2018
prev sibling parent reply Seb <seb wilzba.ch> writes:
On Thursday, 19 July 2018 at 13:10:01 UTC, Martin Tschierschke 
wrote:

 There should be a big section for well done dub.sdl / dub.json 
 examples.


Yes, there should be!
As always it just requires someone to step up, collect and add 
these examples.
FWIW the dub and vibe.d repositories both contain a great 
selection of dub.sdl examples.


 What about defining "comment" as an special keyword for the 
 .json parser inside Dub
 (just ignoring the content") to allow some kind comments inside 
 .json
 In the moment only dub.sdl may be more descriptive with 
 #comments.


It's // or /* ... */ in dub.sdl ;-)


 But many people prefer .json  where no comments are build in.

 So allow to write "comment" : "This string will will be parsed 
 away",
  may do the difference?


As you mentioned SDL already supports comments. JSON support was 
actually only added because too many people complained about SDL 
not being properly supported.
Modifying the JSON parser is a bad idea as it will make 
integration with other tools harder.
Actually the JSON parser already accepts dub.json files with a 
trailing comma which isn't valid JSON and has thus already 
resulted in a bit of pain for tool authors as they can't use an 
off-the-shelf JSON parser anymore.
Currently, dub.json doesn't complain about unused fields (see 
https://run.dlang.io/is/2bbrN8), so you can already do the 
"comment" hack and if/once we actually check for valid field 
names, 'comment' could then be ignored.
Jul 19 2018
parent Jonathan M Davis <newsgroup.d jmdavisprog.com> writes:
On Thursday, July 19, 2018 13:51:25 Seb via Digitalmars-d-announce wrote:

 As you mentioned SDL already supports comments. JSON support was
 actually only added because too many people complained about SDL
 not being properly supported.


Actually, originally, dub only supported json. sdl came later. However,
there was a lot of push back when Sonke made sdl the default, so json not
only didn't get phased out, but it became the default again.

- Jonathan M Davis
Jul 19 2018