www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - DMD is now part of the doc pages on dlang.org

reply Seb <seb wilzba.ch> writes:
Hi all,

I have excellent news on the front of DMD becoming a library.

DMD on dlang.org
----------------

Since today DMD's documentation is browseable online on the 
released docs:

Ddoc: https://dlang.org/phobos/ddmd_mars.html
Ddox: https://dlang.org/library/ddmd/mars.html

In particular this is pretty handy with DDox's symbol search (top 
right), see e.g. [2] for example screenshots.
I guess that not many people noticed, but the prereleases pages 
(i.e. the current master branch) contained the DMD pages for 
quite some time:

Ddoc: https://dlang.org/phobos-prerelease/ddmd_mars.html
Ddox: https://dlang.org/library-prerelease/ddmd/mars.html

Status quo
----------

Many pages aren't well-documented for now and the blacklist of 
exposed modules [3] needs some expansion as well.
However, fixing these pages is now just a PR away (see the 
"Improve this page" button on the top-right).

Building DMD documentation pages
--------------------------------

If you build the pages yourself, you will be interested in the 
`-prerelease` ones as they are built from latest (i.e. your local 
dmd repository).
Just clone dlang.org and for the Ddoc pages, execute the 
`dmd-prerelease` target:

make -f posix.mak dmd-prerelease html

Of course the `html` target is only needed once and don't get 
confused by the files being in web/phobos-prerelease.
Or alternatively with Ddox (and the files being in 
web/library-prerelease):

make -f posix.mak apidocs-prerelease

There's also a bit hidden target that will spawn a Vibe.d 
instance and is faster to start as it only renders a 
documentation page on-demand:

make -f posix.mak apidocs-serve

Other work
----------

- Jacob is putting a ton of effort into making DMD easily 
accessible via DUB [4]
- Razvan is making sure that you can use the resulting library [5]

[1] Enable DMD docs on dlang.org PR: 
https://github.com/dlang/dlang.org/pull/1671
[2] DDox search examples : http://imgur.com/a/lddjt
[3] Module blacklist: 
https://github.com/dlang/dlang.org/blob/master/posix.mak#L73
[4] DMD as DUB package PR: https://github.com/dlang/dmd/pull/6771
[5] DMD as a library PR: https://github.com/dlang/dmd/pull/6836
Jun 06
next sibling parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 6/6/2017 3:13 PM, Seb wrote:
 Hi all,
 
 I have excellent news on the front of DMD becoming a library.
 
 DMD on dlang.org
 ----------------
 
 Since today DMD's documentation is browseable online on the released docs:
 
 Ddoc: https://dlang.org/phobos/ddmd_mars.html
 Ddox: https://dlang.org/library/ddmd/mars.html
This is quite nice! While the ddoc state of the dmd source code is execrable, it provides great motivation for improving it.
Jun 06
parent reply Wulfklaue <wulfklaue wulfklaue.com> writes:
On Wednesday, 7 June 2017 at 00:17:30 UTC, Walter Bright wrote:
 On 6/6/2017 3:13 PM, Seb wrote:
 Hi all,
 
 I have excellent news on the front of DMD becoming a library.
 
 DMD on dlang.org
 ----------------
 
 Since today DMD's documentation is browseable online on the 
 released docs:
 
 Ddoc: https://dlang.org/phobos/ddmd_mars.html
 Ddox: https://dlang.org/library/ddmd/mars.html
This is quite nice! While the ddoc state of the dmd source code is execrable, it provides great motivation for improving it.
Slightly offtopic but why are there two documentation libraries. I found the dlang.org/library version way more readable. Did not even realized this existed. Mass dumped documentation in a single document is so year 2000 :) Second question: I wanted to add a simple example to: https://dlang.org/library/std/datetime/date.to_string.html But the link "Improve this page" results in a dead page. https://github.com/dlang/phobos/edit/master/std/datetime.d#L13022 The datatime file is not located in that position. https://github.com/dlang/phobos/blob/master/std/datetime/date.d This is the correct location.
Jun 07
next sibling parent reply rikki cattermole <rikki cattermole.co.nz> writes:
On 07/06/2017 12:30 PM, Wulfklaue wrote:
 On Wednesday, 7 June 2017 at 00:17:30 UTC, Walter Bright wrote:
 On 6/6/2017 3:13 PM, Seb wrote:
 Hi all,

 I have excellent news on the front of DMD becoming a library.

 DMD on dlang.org
 ----------------

 Since today DMD's documentation is browseable online on the released 
 docs:

 Ddoc: https://dlang.org/phobos/ddmd_mars.html
 Ddox: https://dlang.org/library/ddmd/mars.html
This is quite nice! While the ddoc state of the dmd source code is execrable, it provides great motivation for improving it.
Slightly offtopic but why are there two documentation libraries. I found the dlang.org/library version way more readable. Did not even realized this existed. Mass dumped documentation in a single document is so year 2000 :) Second question: I wanted to add a simple example to: https://dlang.org/library/std/datetime/date.to_string.html But the link "Improve this page" results in a dead page. https://github.com/dlang/phobos/edit/master/std/datetime.d#L13022 The datatime file is not located in that position. https://github.com/dlang/phobos/blob/master/std/datetime/date.d This is the correct location.
std.datetime has been very recently broken up, it hasn't been in a release as of yet. Give it a release, it'll be fixed.
Jun 07
parent Wulfklaue <wulfklaue wulfklaue.com> writes:
On Wednesday, 7 June 2017 at 11:37:21 UTC, rikki cattermole wrote:
 std.datetime has been very recently broken up, it hasn't been 
 in a release as of yet. Give it a release, it'll be fixed.
Ok, thanks. Just my bad luck for trying out the one part that just got broken up. *haha*
Jun 07
prev sibling parent Seb <seb wilzba.ch> writes:
On Wednesday, 7 June 2017 at 11:30:47 UTC, Wulfklaue wrote:
 Slightly offtopic but why are there two documentation 
 libraries. I found the dlang.org/library version way more 
 readable. Did not even realized this existed.

 Mass dumped documentation in a single document is so year 2000 
 :)
Ddoc (/phobos, aka the builtin -D flag in the compiler) was first and the process of replacing it with DDox (https://github.com/rejectedsoftware/ddox) is taking quite some time, because the output isn't identical and there are still some "design" issues with Ddox, see e.g. this PR for an overview: https://github.com/dlang/dlang.org/pull/1526 The transition started about three years ago and I think it just doesn't bother anyone enough to work on it: https://github.com/dlang/dlang.org/pull/695
 Second question:

 I wanted to add a simple example to:

 https://dlang.org/library/std/datetime/date.to_string.html


 But the link "Improve this page" results in a dead page.

 https://github.com/dlang/phobos/edit/master/std/datetime.d#L13022

 The datatime file is not located in that position.

 https://github.com/dlang/phobos/blob/master/std/datetime/date.d

 This is the correct location.
The "View the source" code link uses a link to the latest stable release (i.e. the one that is deployed on dlang.org, currently 2.074.1): https://github.com/dlang/phobos/blob/v2.074.1/std/datetime.d#L13022 The "Improve this page" links to `master`, because you want to improve the file at the `master` branch, which admittedly can be a bit tricky. When you want to modify `master` branch, the `-prerelease` pages are your friend, e.g. https://dlang.org/library-prerelease/std/datetime/date/date.to_string.html
Jun 07
prev sibling parent reply Brad Roberts via Digitalmars-d <digitalmars-d puremagic.com> writes:
No idea how much work it is to add another section specifically for the 
front end, but the front end docs really don't belong co-mingled with 
the phobos and library directories.  It's part of neither.

On 6/6/17 3:13 PM, Seb via Digitalmars-d wrote:
 Hi all,
 
 I have excellent news on the front of DMD becoming a library.
 
 DMD on dlang.org
 ----------------
 
 Since today DMD's documentation is browseable online on the released docs:
 
 Ddoc: https://dlang.org/phobos/ddmd_mars.html
 Ddox: https://dlang.org/library/ddmd/mars.html
 
 In particular this is pretty handy with DDox's symbol search (top 
 right), see e.g. [2] for example screenshots.
 I guess that not many people noticed, but the prereleases pages (i.e. 
 the current master branch) contained the DMD pages for quite some time:
 
 Ddoc: https://dlang.org/phobos-prerelease/ddmd_mars.html
 Ddox: https://dlang.org/library-prerelease/ddmd/mars.html
 
 Status quo
 ----------
 
 Many pages aren't well-documented for now and the blacklist of exposed 
 modules [3] needs some expansion as well.
 However, fixing these pages is now just a PR away (see the "Improve this 
 page" button on the top-right).
 
 Building DMD documentation pages
 --------------------------------
 
 If you build the pages yourself, you will be interested in the 
 `-prerelease` ones as they are built from latest (i.e. your local dmd 
 repository).
 Just clone dlang.org and for the Ddoc pages, execute the 
 `dmd-prerelease` target:
 
 make -f posix.mak dmd-prerelease html
 
 Of course the `html` target is only needed once and don't get confused 
 by the files being in web/phobos-prerelease.
 Or alternatively with Ddox (and the files being in web/library-prerelease):
 
 make -f posix.mak apidocs-prerelease
 
 There's also a bit hidden target that will spawn a Vibe.d instance and 
 is faster to start as it only renders a documentation page on-demand:
 
 make -f posix.mak apidocs-serve
 
 Other work
 ----------
 
 - Jacob is putting a ton of effort into making DMD easily accessible via 
 DUB [4]
 - Razvan is making sure that you can use the resulting library [5]
 
 [1] Enable DMD docs on dlang.org PR: 
 https://github.com/dlang/dlang.org/pull/1671
 [2] DDox search examples : http://imgur.com/a/lddjt
 [3] Module blacklist: 
 https://github.com/dlang/dlang.org/blob/master/posix.mak#L73
 [4] DMD as DUB package PR: https://github.com/dlang/dmd/pull/6771
 [5] DMD as a library PR: https://github.com/dlang/dmd/pull/6836
Jun 06
parent Seb <seb wilzba.ch> writes:
On Wednesday, 7 June 2017 at 00:29:24 UTC, Brad Roberts wrote:
 No idea how much work it is to add another section specifically 
 for the front end, but the front end docs really don't belong 
 co-mingled with the phobos and library directories.  It's part 
 of neither.
Not that much: 1) Ddoc: adjust DOC_OUTPUT_DIR for dmd-release and dmd-prerelease https://github.com/dlang/dlang.org/blob/master/posix.mak#L374 2) Ddox: (a bit more complicated) - split the dmd modules into a separate docs-dmd.json and docs-dmd-prerelease.json https://github.com/dlang/dlang.org/blob/master/posix.mak#L507 - Add the DDoc generation target (aka as sitemap XML + htaccess) without creating too much duplication https://github.com/dlang/dlang.org/blob/master/posix.mak#L478 3) Add menu links to it https://github.com/dlang/dlang.org/blob/master/dlang.org.ddoc#L243 I just went with dumping it at /phobos{,-prerelease} and /library{,-prerelease} because this was the easiest.
Jun 06