[Issue 16425] New: DUB "Getting Started" is seriously wanting

[via Digitalmars-d-bugs]

https://issues.dlang.org/show_bug.cgi?id=16425

          Issue ID: 16425
           Summary: DUB "Getting Started" is seriously wanting
           Product: D
           Version: D2
          Hardware: All
                OS: All
            Status: NEW
          Severity: normal
          Priority: P1
         Component: dlang.org
          Assignee: nobody at puremagic.com
          Reporter: bugzilla at digitalmars.com

As reported by Andrei on the n.g.:

So I've set out to set up a dub package for
https://github.com/dlang/phobos/pull/4613 from a position of total ignorance.
Naturally I went with http://code.dlang.org/getting_started and found it
wanting.

* It gives instructions on how to install dub, but does not mention "sudo
apt-get install dub" which I tried randomly and just worked. Well that should
be mentioned.

* I'd expect and hope a "getting started" doc to take me from nothing to "I got
a hello world package going", then point me to advanced option. Instead,
http://code.dlang.org/getting_started gives a flat overview of everything dub
can do, from the simplest (single-file packages) to the rather esoteric
(foreign projects, advanced dependencies). Then it gives me links to things
like "package format specification", completely leaving me in the dark as to
what in the world I need to do from where I am to where I want to be (have a
library packaged).

* In an extra twinge of irony, the link to the package format specification
goes to http://code.dlang.org/package-format?lang=json, i.e. the JSON format.
Which is of course not what "dub init" (which I duly ran because it was on the
getting started page) generated. It was no source of confusion to me because I
had the context, but it may for others.

* So I look at the SDL spec and even after I'm done I have no idea where to
specify "I have a package called checkedint, and the only file for it is
./checkedint/checkedint.d". I do know what I'd need to do if I had subpackages
though.

* At this point I've read two full pages of documentation and I have no idea
how to (a) define my package for one library with one file in it, and (b) build
it. Literally: no idea.

* So I assume on a hunch that since the package name is "checkedint" and there
is a homonym directory, there might be some nice automatic setting to pick that
up. So I go to dub's Command Line documentation.

* I see the default is "run" so I go to the initial dir where I ran "dub init
checkedint" and issue "dub". No go. I figure I need to go inside the checkedint
dir (nice error msg). OK, that builds a library. Nice.

* Next thing I want is to unittest the thing. Searching the cmdline docs, first
hit suggests "dub --build=unittest" is the way to go. It does build, but
doesn't run the unittests. Fortunately I keep on searching and find that "dub
test" does what I want.

So here we are. Hope this helps building a simpler, clear tutorial. The
"Getting Started" document is really "Documentation Root".

--