www.digitalmars.com         C & C++   DMDScript  

digitalmars.D.announce - Documentation for any* dub package, any version

reply Adam D. Ruppe <destructionator gmail.com> writes:
Many of you will already know this from the other thread or from 
my twitter, but I just added a on-demand downloader to my 
dpldocs.info domain to fetch and build docs for any* dub package.

Simply go to projectname.dpldocs.info/vX.Y.Z/ and it will 
generate docs for dub package projectname, version X.Y.Z. (If you 
don't specify a version, it will pull the master branch.)

For example:

http://arsd-official.dpldocs.info/arsd.html

master branch for the arsd-official package

or:

http://dplug.dpldocs.info/v6.0.22/dplug.html

6.0.22 of the dplug package.

etc.

I'd like to get the code.dlang.org folks to add the correct link 
to the main package site so people can easily discover this.... 
just put nofollow on it plz so google doesn't trigger generation 
of pages people don't actually need (the lazy generation + 
caching allows me to host this on a cheap VPS)


It builds the docs using my own doc generator 
<https://github.com/adamdruppe/adrdox> which pulls embedded doc 
comments out of the source.

It isn't 100% compatible with ddoc. For example, this 
user-defined macro was not expanded: 
http://dxml.dpldocs.info/dxml.dom.html#source

But, it builds 99% of Phobos so it can probably build your 
project too! And get the ease of adrdox navigation and legibility.

Moreover, if you want to embrace it, you can use all the features 
described here: 
http://dpldocs.info/experimental-docs/adrdox.syntax.html except 
for the LaTeX math generation (that's not installed on the dub 
doc server I set up).

You can group functions like seen here: 
http://dpldocs.info/experimental-docs/arsd.nanovega.html and use 
some markdown syntax, and easy [reference] linking and more.



The generated docs may get some customization options in the 
future, like adding a logo, header nav links, or maybe tweaking 
the color scheme. It will probably also start reading .gitignore 
and perhaps a .adrdoxignore file soon to to exclude files from 
generation. I just need to decide the details first and it is 
time to work the day job right now and I want to announce sooner 
rather than later :)


* currently, only github code downloading is actually implemented.
Feb 26 2018
next sibling parent Guillaume Piolat <notthat email.com> writes:
On Monday, 26 February 2018 at 14:59:07 UTC, Adam D. Ruppe wrote:

 Many of you will already know this from the other thread or 
 from my twitter, but I just added a on-demand downloader to my 
 dpldocs.info domain to fetch and build docs for any* dub 
 package.


This is very much awesome, much cleaner than generating docs 
locally imho.
Congrats!


 I'd like to get the code.dlang.org folks to add the correct 
 link to the main package site so people can easily discover 
 this.... just put nofollow on it plz so google doesn't trigger 
 generation of pages people don't actually need (the lazy 
 generation + caching allows me to host this on a cheap VPS)


Perhaps a case robots.txt being useful for once?
Feb 26 2018
prev sibling next sibling parent reply aliak <something something.com> writes:
On Monday, 26 February 2018 at 14:59:07 UTC, Adam D. Ruppe wrote:

 Many of you will already know this from the other thread or 
 from my twitter, but I just added a on-demand downloader to my 
 dpldocs.info domain to fetch and build docs for any* dub 
 package.

 Simply go to projectname.dpldocs.info/vX.Y.Z/ and it will 
 generate docs for dub package projectname, version X.Y.Z. (If 
 you don't specify a version, it will pull the master branch.)

 For example:

 http://arsd-official.dpldocs.info/arsd.html

 master branch for the arsd-official package

 or:

 http://dplug.dpldocs.info/v6.0.22/dplug.html

 6.0.22 of the dplug package.

 etc.

 I'd like to get the code.dlang.org folks to add the correct 
 link to the main package site so people can easily discover 
 this.... just put nofollow on it plz so google doesn't trigger 
 generation of pages people don't actually need (the lazy 
 generation + caching allows me to host this on a cheap VPS)


 It builds the docs using my own doc generator 
 <https://github.com/adamdruppe/adrdox> which pulls embedded doc 
 comments out of the source.

 It isn't 100% compatible with ddoc. For example, this 
 user-defined macro was not expanded: 
 http://dxml.dpldocs.info/dxml.dom.html#source

 But, it builds 99% of Phobos so it can probably build your 
 project too! And get the ease of adrdox navigation and 
 legibility.

 Moreover, if you want to embrace it, you can use all the 
 features described here: 
 http://dpldocs.info/experimental-docs/adrdox.syntax.html except 
 for the LaTeX math generation (that's not installed on the dub 
 doc server I set up).

 You can group functions like seen here: 
 http://dpldocs.info/experimental-docs/arsd.nanovega.html and 
 use some markdown syntax, and easy [reference] linking and more.



 The generated docs may get some customization options in the 
 future, like adding a logo, header nav links, or maybe tweaking 
 the color scheme. It will probably also start reading 
 .gitignore and perhaps a .adrdoxignore file soon to to exclude 
 files from generation. I just need to decide the details first 
 and it is time to work the day job right now and I want to 
 announce sooner rather than later :)


 * currently, only github code downloading is actually 
 implemented.


This is awesome! Worked great. I use ddox right now (eg: 
https://aliak00.github.io/optional/) and your front page is way 
better and the source links are gold!

Questions: Tried it with optional and undocumented stuff is also 
shown. Will this be the default or? What's the recommended way to 
not have some modules in there at this time, if any?

Currently I have a internal.d (e.g. 
https://github.com/aliak00/optional/blob/master/source/optional/internal.d)
which has public imports because I want to include it everywhere in my project
and have all files have access to (though I think I may need to read up on
access controls and modules cause I've just been winging it).

Thanks for this, with theming support I think I'd switch to this 
in me personal repos at least.

Cheers
Feb 26 2018
parent reply Adam D. Ruppe <destructionator gmail.com> writes:
On Monday, 26 February 2018 at 15:21:55 UTC, aliak wrote:

 Questions: Tried it with optional and undocumented stuff is 
 also shown.


Oh, fixed now. since there's no ddoc at all in that file, it 
should have been skipped, I just had a testing "return true;" in 
the method I forgot to remove.

And then for the internal ones, I also just made it consider any 
module/package called "internal" to be automatically skipped too 
because that's a fairly common pattern.

So try this now:
http://optional.dpldocs.info/optional.html

it it cuts those other modules out.


 What's the recommended way to not have some modules in there at 
 this time, if any?


ketmar sent me a patch to parse a .adrdox_ignore file, in the 
same format as gitignore, which I merged but haven't pushed to 
that server yet. I'm not sure that's the exact approach I want to 
take, but something like that will be an option soon too if the 
default doesn't work out.


 Thanks for this, with theming support I think I'd switch to 
 this in me personal repos at least.


Yeah, I just need to decide how I want that to look in the repo 
too (if you download adrdox yourself, you can change the 
skeleton.html and style.css files locally. style.css is a bit of 
a mess tho but it can be done, i did a dark color scheme here to 
use as a test. but how to do that on the central host? idk yet, 
maybe it can read a custom file out of the git repo, or add some 
option to dub.json.). but that will prolly be a week or two 
before i get around to it.
Feb 26 2018
parent reply aliak <something something.com> writes:
On Monday, 26 February 2018 at 18:17:51 UTC, Adam D. Ruppe wrote:

 Oh, fixed now. since there's no ddoc at all in that file, it 
 should have been skipped, I just had a testing "return true;" 
 in the method I forgot to remove.


Nice :D Looks good.


 ketmar sent me a patch to parse a .adrdox_ignore file, in the 
 same format as gitignore, which I merged but haven't pushed to 
 that server yet. I'm not sure that's the exact approach I want 
 to take, but something like that will be an option soon too if 
 the default doesn't work out.


Awesome. good start at least, and just to throw an approach out 
there for your consideration, a .adrdox.yml file with a 
include/exclude/style/etc keys might be a good way to go.


 Yeah, I just need to decide how I want that to look in the repo 
 too (if you download adrdox yourself, you can change the 
 skeleton.html and style.css files locally. style.css is a bit 
 of a mess tho but it can be done, i did a dark color scheme 
 here to use as a test. but how to do that on the central host? 
 idk yet, maybe it can read a custom file out of the git repo, 
 or add some option to dub.json.). but that will prolly be a 
 week or two before i get around to it.


Great! Think I'll give the skeleton/style a hack at some point 
indeed. Maybe if it's a central host then styling should just be 
homogeneous across the board as well for consistency and all?

Cheers
Feb 26 2018
parent Adam D. Ruppe <destructionator gmail.com> writes:
On Monday, 26 February 2018 at 20:15:13 UTC, aliak wrote:

 Awesome. good start at least, and just to throw an approach out 
 there for your consideration, a .adrdox.yml file with a 
 include/exclude/style/etc keys might be a good way to go.


Yeah, that's basically what I was thinking (though not yml, I'd 
use a sane, well-support language. actually I'd probably just use 
xml.)


 Great! Think I'll give the skeleton/style a hack at some point 
 indeed.


Well, that's if you download and host the stuff yourself. Though 
my css file is kinda intertwined, it has the mobile responsive 
stuff in there next to content presentation and syntax highlight 
colors, etc....


 Maybe if it's a central host then styling should just be 
 homogeneous across the board as well for consistency and all?


yeah, maybe that too.
Feb 26 2018
prev sibling next sibling parent reply Jonathan M Davis <newsgroup.d jmdavisprog.com> writes:
On Monday, February 26, 2018 14:59:07 Adam D. Ruppe via Digitalmars-d-
announce wrote:

 It isn't 100% compatible with ddoc. For example, this
 user-defined macro was not expanded:
 http://dxml.dpldocs.info/dxml.dom.html#source


Yeah. Any project that uses .ddoc files to define additional macros isn't
going to work properly, whereas projects that make no attempt to define
stuff like linking macros and just have documentation using the predefined
macros should work just fine.

- Jonathan M Davis
Feb 26 2018
parent reply Adam D. Ruppe <destructionator gmail.com> writes:
On Monday, 26 February 2018 at 15:49:19 UTC, Jonathan M Davis 
wrote:

 Yeah. Any project that uses .ddoc files to define additional 
 macros isn't going to work properly


It is actually more than that: I don't support user-defined ddoc 
macros at all. About 3/4 of the ones I've seen are just link 
macros.... instead of everyone creating their own random mix 
(like LREF, LREF2, REF, REF_ALTTEXT, PHOBOS_REF, 
PHOBOS_REF_ALTTEXT, OBJECT_REF...), I just have a built-in, 
simple, unified syntax: [symbol|alt text] where alt text is 
optional and symbol is looked up according to D scope rules. (you 
can also define custom symbols for things like author name links).

I link to the source automatically too, including to the specific 
line of the correct overload for functions, so no need for macros 
to do those.

Much easier to write in code: no more need to remember what this 
project decided to name its macro.

(keep in mind that adrdox is explicitly NOT ddoc. I dropped a few 
ddoc misfeatures and modified some in a non-compatible way. I've 
given up on trying to save ddoc, it is rotten to the core.)
Feb 26 2018
next sibling parent reply Jonathan M Davis <newsgroup.d jmdavisprog.com> writes:
On Monday, February 26, 2018 19:51:27 Adam D. Ruppe via Digitalmars-d-
announce wrote:

 On Monday, 26 February 2018 at 15:49:19 UTC, Jonathan M Davis

 wrote:

 Yeah. Any project that uses .ddoc files to define additional
 macros isn't going to work properly


 It is actually more than that: I don't support user-defined ddoc
 macros at all. About 3/4 of the ones I've seen are just link
 macros.... instead of everyone creating their own random mix
 (like LREF, LREF2, REF, REF_ALTTEXT, PHOBOS_REF,
 PHOBOS_REF_ALTTEXT, OBJECT_REF...), I just have a built-in,
 simple, unified syntax: [symbol|alt text] where alt text is
 optional and symbol is looked up according to D scope rules. (you
 can also define custom symbols for things like author name links).

 I link to the source automatically too, including to the specific
 line of the correct overload for functions, so no need for macros
 to do those.

 Much easier to write in code: no more need to remember what this
 project decided to name its macro.

 (keep in mind that adrdox is explicitly NOT ddoc. I dropped a few
 ddoc misfeatures and modified some in a non-compatible way. I've
 given up on trying to save ddoc, it is rotten to the core.)


Well, then basically, projects are going to need to decide to go with adrdox
over ddoc if they want clean documentation. They'll probably get better
documentation with adrdox than the default ddoc if they do nothing, but any
project that actually goes to the effort of having nice looking
documentation is going to fall flat on its face with adrdox unless it buys
into adrdox whole hog.

dxml would be a prime example of a project that won't work with adrdox
though given that it tries to emulate what Phobos has done with its
documentation, and many of the macros are the same, which should minimize
how much the documentation will have to be mucked with if it ever ends up in
Phobos, but that means that it is very much not vanilla ddoc, let alone
adrdox.

- Jonathan M Davis
Feb 26 2018
parent reply Adam D. Ruppe <destructionator gmail.com> writes:
On Tuesday, 27 February 2018 at 01:43:55 UTC, Jonathan M Davis 
wrote:

 Well, then basically, projects are going to need to decide to 
 go with adrdox over ddoc if they want clean documentation.


That's right, and I can't imagine anyone is going to put hours of 
work into ddoc when they can spend seconds just writing and have 
it just work on my site, including most common ddoc in addition 
to a good subset of markdown and, if they decide to dive a little 
bit deeper, can use my custom syntax custom-tailored to writing D 
documentation quickly and easily like [link].

https://www.youtube.com/watch?v=Ak516vtDTEA


 They'll probably get better documentation with adrdox than the 
 default ddoc if they do nothing, but any project that actually 
 goes to the effort of having nice looking documentation is 
 going to fall flat on its face with adrdox unless it buys into 
 adrdox whole hog.


Eh, that's not true. I am *very* compatible with Phobos (have you 
use dpldocs.info before? 9/10 dentists agree, it is vastly 
superior to dlang.org, and the tenth dentist is paid to lie), and 
since most "nicer" ddoc borrows from the phobos definitions, most 
of them will just work too. I actually even just added your LREF2 
macro to the internal macro compatibility list, bringing my 
compatibly with your syntax to near-total.

BTW you misspelled "element" here:
http://dxml.dpldocs.info/source/dxml.dom.d.html#L119

On your version, third paragraph:


adrdox (my build here anyway, which knows the whole phobos tree 
too) caught that and issued a broken link warning. Did ddoc? I 
already know the answer.

Of course, if you were using adrdox syntax, that mistake wouldn't 
have happened in the first place, instead of writing:

   $(REF_ALTTEXT EntityType.elementStart, EntityType.elmentStart, 
dxml, parser)

You would have simply wrote [EntityType.elementStart] and not had 
to repeat yourself telling the compiler what it already knows (in 
a bizarre order, no less).


Of course, even with the broken link, the adrdox result is usable:

http://dxml.dpldocs.info/dxml.dom.parseDOM.2.html

links to:
http://dxml.dpldocs.info/dxml.parser.EntityType.html#elmentStart

and you can see it in the table.

Whereas the ddoc link goes to:


where the anchor is who-knows-where.


Moreover, look at this:
http://dxml.dpldocs.info/dxml.util.asNormalized.html

"combines parseStdEntityRef and parseCharRef along with 
processing for $(DCODE_STRING '\r') to"

and compare with:


"combines parseStdEntityRef and parseCharRef along with 
processing for to "


See something missing? Yes, you write DCODE_STRING instead of the 
definition of D_CODE_STRING and ddoc swallowed your text. (Yes, I 
know you can define ddoc to output undefined macros, just like 
adrdox does. But it doesn't by default, so a typo in a macro name 
means text just ~disappears~.)


And again, that is unlikely to have happened if you just used the 
standard backticks (`'\r'`) which don't render exactly the same 
but are good enough. ddoc supports them too, so this isn't even 
an adrdox thing... but I'd argue that merely having user-defined 
macros makes you more likely to try to use them, increasing the 
likelihood for mistakes like this. That's the main reason why I 
decided to simply not support them, the cost outweighs the 
benefits.



I don't say this to pick on you - you have some of the nicest 
ddoc I have ever seen, and you actually make the effort to write 
it all up in the first place.

But even you, who know how to use ddoc very well and have 
obviously spent some time on it here, made trivial mistakes here 
that just don't happen with adrdox.
Feb 26 2018
parent Jonathan M Davis <newsgroup.d jmdavisprog.com> writes:
On Tuesday, February 27, 2018 02:26:49 Adam D. Ruppe via Digitalmars-d-
announce wrote:

 But even you, who know how to use ddoc very well and have
 obviously spent some time on it here, made trivial mistakes here
 that just don't happen with adrdox.


Any time you do something manually instead of it being automatic, there's a
risk of that.

And if adrdox works well for folks, then great. Personally, I'd like to
stick to the official tool, especially when I'm writing something that might
make it into Phobos (though like Phobos, I was forced to add a helper
program in order to deal with stuff like the navigation bar), but there are
definitely aspects of it which make it harder to use than adrdox or ddox.

Thanks for pointing out those mistakes.

- Jonathan M Davis
Feb 26 2018
prev sibling next sibling parent reply "H. S. Teoh" <hsteoh quickfur.ath.cx> writes:
On Mon, Feb 26, 2018 at 06:43:55PM -0700, Jonathan M Davis via
Digitalmars-d-announce wrote:
[...]

 Well, then basically, projects are going to need to decide to go with
 adrdox over ddoc if they want clean documentation. They'll probably
 get better documentation with adrdox than the default ddoc if they do
 nothing, but any project that actually goes to the effort of having
 nice looking documentation is going to fall flat on its face with
 adrdox unless it buys into adrdox whole hog.
 
 dxml would be a prime example of a project that won't work with adrdox
 though given that it tries to emulate what Phobos has done with its
 documentation, and many of the macros are the same, which should
 minimize how much the documentation will have to be mucked with if it
 ever ends up in Phobos, but that means that it is very much not
 vanilla ddoc, let alone adrdox.


[...]

It's a sorry state of affairs.  I dream of the day when I can just write
code and documentation as-is, and downstream users can just use whatever
doc formatting system they like and it will all Just Work(tm).

Basically, it requires a standard way of writing documentation that
every backend tool understands and supports, be it ddoc or adrdox or
whatever else you fancy.  But I'm not holding my breath for that to
materialize.


T

-- 
Unix is my IDE. -- Justin Whear
Feb 26 2018
parent reply Adam D. Ruppe <destructionator gmail.com> writes:
On Tuesday, 27 February 2018 at 01:53:23 UTC, H. S. Teoh wrote:

 It's a sorry state of affairs.  I dream of the day when I can 
 just write code and documentation as-is, and downstream users 
 can just use whatever doc formatting system they like and it 
 will all Just Work(tm).


Join me, and together, we can rule the D-alaxy as coder and 
coder! https://www.youtube.com/watch?v=tzvY1OzoDbQ


 But I'm not holding my breath for that to materialize.


Saturday morning, a user complained that several leading dub 
packages had poor documentation, if they could find it at all. 
That's changing, right now.

Before long, packages without docs are going to suffer. This will 
put pressure on authors to have *something* written, and I'm 
providing the lowest cost for greatest benefit to help your 
package succeed in the market.

In the end? Everybody wins.

Package authors get an automatic documentation build that is 
discoverable, legible, searchable and navigable. They can just 
write plain text (or some markdown) and it just works, or go 
deeper and use the advanced toolset I have to offer, allowing 
them to focus on documenting their libraries instead of 
struggling with the documentation system.

Package users get links that work and can more quickly locate and 
evaluate packages before using them, and use them more 
effectively after deciding to go forward.

And, of course, I win because I get power! UNLIMITED POWER!
Feb 26 2018
parent reply psychoticRabbit <meagain meagain.com> writes:
On Tuesday, 27 February 2018 at 02:57:08 UTC, Adam D. Ruppe wrote:

 Saturday morning, a user complained that several leading dub 
 packages had poor documentation, if they could find it at all. 
 That's changing, right now.

 Before long, packages without docs are going to suffer. This 
 will put pressure on authors to have *something* written, and 
 I'm providing the lowest cost for greatest benefit to help your 
 package succeed in the market.


Uhh? I don't get...why coders need to write documentation?

.. it doesn't make any sense.

stop this nonsense... at once!
Feb 26 2018
parent "H. S. Teoh" <hsteoh quickfur.ath.cx> writes:
On Tue, Feb 27, 2018 at 03:07:10AM +0000, psychoticRabbit via
Digitalmars-d-announce wrote:
[...]

 Uhh? I don't get...why coders need to write documentation?


[...]

To communicate with other coders who will need to read and maintain the
code.

And by "other coders", of course, I mean yourself, 2 months later. :-D

If you've ever stared at some code you wrote 5 months ago (or worse, 15
years ago) and wondered, "who wrote this crap" or "what on earth what I
thinking about at the time?!", you'll know what I mean. :-P


T

-- 
The volume of a pizza of thickness a and radius z can be described by the
following formula: pi zz a. -- Wouter Verhelst
Feb 26 2018
prev sibling parent reply David Gileadi <gileadisNOSPM gmail.com> writes:
On 2/26/18 12:51 PM, Adam D. Ruppe wrote:

 ... I just have 
 a built-in, simple, unified syntax: [symbol|alt text] where alt text is 
 optional and symbol is looked up according to D scope rules. (you can 
 also define custom symbols for things like author name links).
 
 I link to the source automatically too, including to the specific line 
 of the correct overload for functions, so no need for macros to do those.


Out of curiosity, what prompted [symbol|alt text] instead of going with 
the Markdown construct of [alt text][symbol]? I ask because if I'm able 
to get my Markdown support merged into DDoc, I'd like to support 
[symbol] and [alt text][symbol] links.
Feb 27 2018
parent reply Adam D. Ruppe <destructionator gmail.com> writes:
On Tuesday, 27 February 2018 at 16:00:26 UTC, David Gileadi wrote:

 Out of curiosity, what prompted [symbol|alt text] instead of 
 going with the Markdown construct of [alt text][symbol]?


Well, markdown is [alt text](url), and adrdox actually DOES 
support that as well:

http://dpldocs.info/experimental-docs/adrdox.syntax.html#markdown-style-links

(I just added that last Friday though for gtkd docs 
compatibility!)

Though it does NOT support a symbol in there, just a URL right 
now. Maybe I can add it, but I always start conservative - allow 
the least syntax with the most restrictions I can, then loosen 
them as I'm sure it isn't annoying.


But anyway, the [symbol|alt text] comes from Wikipedia's markup 
actually, which is the first thing that comes to my mind to 
easily cross-link articles. On wikipedia, you use brackets to 
indicate a word as a link: `director = [[Avery Brooks]]`, for 
example, will link to that article. Similarly, `[[Star Trek: Deep 
Space Nine (season 6)|6]]` will just show the text "6", while 
linking to the page in there.

So I took that and generalized it a bit so it supports other URLs 
too, then simplified it to just one set of [] instead of two.


The big advantage for [] over markdown links is it is lighter 
syntax in the simple case:

/// See also: [intersect]

knows to link to the symbol `intersect`. Whereas:

/// See also: [intersect](intersect)

would be the equivalent markdown style, but it is repeated... so 
you might skip the alt text:

/// See also: (intersect)

but that conflicts with very common parenthetical text like "I 
think that's silly (sorta)..." and I wouldn't want "sorta" to be 
linked there!

So I just went with [].
Feb 27 2018
parent reply David Gileadi <gileadisNOSPM gmail.com> writes:
On 2/27/18 9:21 AM, Adam D. Ruppe wrote:

 On Tuesday, 27 February 2018 at 16:00:26 UTC, David Gileadi wrote:

 Out of curiosity, what prompted [symbol|alt text] instead of going 
 with the Markdown construct of [alt text][symbol]?


 
 Well, markdown is [alt text](url), and adrdox actually DOES support that 
 as well:
 
 http://dpldocs.info/experimental-docs/adrdox.syntax.html#markdown-style-links 
 
 
 (I just added that last Friday though for gtkd docs compatibility!)
 
 Though it does NOT support a symbol in there, just a URL right now. 
 Maybe I can add it, but I always start conservative - allow the least 
 syntax with the most restrictions I can, then loosen them as I'm sure it 
 isn't annoying.
 
 
 But anyway, the [symbol|alt text] comes from Wikipedia's markup 
 actually, which is the first thing that comes to my mind to easily 
 cross-link articles. On wikipedia, you use brackets to indicate a word 
 as a link: `director = [[Avery Brooks]]`, for example, will link to that 
 article. Similarly, `[[Star Trek: Deep Space Nine (season 6)|6]]` will 
 just show the text "6", while linking to the page in there.
 
 So I took that and generalized it a bit so it supports other URLs too, 
 then simplified it to just one set of [] instead of two.
 
 
 The big advantage for [] over markdown links is it is lighter syntax in 
 the simple case:
 
 /// See also: [intersect]
 
 knows to link to the symbol `intersect`. Whereas:
 
 /// See also: [intersect](intersect)
 
 would be the equivalent markdown style, but it is repeated... so you 
 might skip the alt text:
 
 /// See also: (intersect)
 
 but that conflicts with very common parenthetical text like "I think 
 that's silly (sorta)..." and I wouldn't want "sorta" to be linked there!
 
 So I just went with [].


Markdown actually supports two kinds of links: inline links (which you 
describe above and I'm very happy you support) and reference links [1].

A reference link can be like [alt text][reference] or you can do the 
shortcut version if your alt text is the same as the reference name: 
[reference]. I currently support both forms in my upcoming Markdown PR, 
but they only link to references that are defined elsewhere in the 
document, like my [1] at the bottom of this message. What I want to do 
is automatically include references for symbols in the current scope, to 
support links to symbols via [symbol] and [alt text][symbol].


[1]: http://spec.commonmark.org/0.28/#reference-link
Feb 27 2018
parent reply Adam D. Ruppe <destructionator gmail.com> writes:
On Tuesday, 27 February 2018 at 16:39:08 UTC, David Gileadi wrote:

 Markdown actually supports two kinds of links: inline links 
 (which you describe above and I'm very happy you support) and 
 reference links [1].


Oh, I have something similar to that too.

http://dpldocs.info/experimental-docs/adrdox.syntax.html#footnotes

I actually didn't realize markdown had such... mine is probably 
not quite compatible... but [text][text] is an uncommon enough 
pattern it might just be workable. I doubt I'd ever write 
[link][link] without a space in between...


 What I want to do is automatically include references for 
 symbols in the current scope, to support links to symbols via 
 [symbol] and [alt text][symbol].


Yeah, that might work on both generators.
Feb 27 2018
parent reply David Gileadi <gileadisNOSPM gmail.com> writes:
On 2/27/18 2:59 PM, Adam D. Ruppe wrote:

 On Tuesday, 27 February 2018 at 16:39:08 UTC, David Gileadi wrote:

 Markdown actually supports two kinds of links: inline links (which you 
 describe above and I'm very happy you support) and reference links [1].


 
 Oh, I have something similar to that too.
 
 http://dpldocs.info/experimental-docs/adrdox.syntax.html#footnotes
 
 I actually didn't realize markdown had such... mine is probably not 
 quite compatible... but [text][text] is an uncommon enough pattern it 
 might just be workable. I doubt I'd ever write [link][link] without a 
 space in between...
 

 What I want to do is automatically include references for symbols in 
 the current scope, to support links to symbols via [symbol] and [alt 
 text][symbol].


 
 Yeah, that might work on both generators.


I hope so. I'm happy that D documentation is nicer to use. Thanks for 
working on it!
Feb 27 2018
parent David Gileadi <gileadisNOSPM gmail.com> writes:
On 2/27/18 3:18 PM, David Gileadi wrote:

 On 2/27/18 2:59 PM, Adam D. Ruppe wrote:

 On Tuesday, 27 February 2018 at 16:39:08 UTC, David Gileadi wrote:

 Markdown actually supports two kinds of links: inline links (which 
 you describe above and I'm very happy you support) and reference 
 links [1].


 Oh, I have something similar to that too.

 http://dpldocs.info/experimental-docs/adrdox.syntax.html#footnotes

 I actually didn't realize markdown had such... mine is probably not 
 quite compatible... but [text][text] is an uncommon enough pattern it 
 might just be workable. I doubt I'd ever write [link][link] without a 
 space in between...


 What I want to do is automatically include references for symbols in 
 the current scope, to support links to symbols via [symbol] and [alt 
 text][symbol].


 Yeah, that might work on both generators.


 
 I hope so. I'm happy that D documentation is nicer to use. Thanks for 
 working on it!


Whoops, should have been "...D documentation is *getting* nicer to use."
Feb 27 2018
prev sibling next sibling parent reply WebFreak001 <d.forum webfreak.org> writes:
On Monday, 26 February 2018 at 14:59:07 UTC, Adam D. Ruppe wrote:

 Many of you will already know this from the other thread or 
 from my twitter, but I just added a on-demand downloader to my 
 dpldocs.info domain to fetch and build docs for any* dub 
 package.

 [...]


amazing! I planned on adding a documentation tab in the current 
dub package overhaul, but I wasn't sure on where to get the data 
from, if I can add this to embed on the dub website (ala iframe) 
it would make a lot much easier! Could you maybe add an API 
endpoint to check if documentation is present (download & cache 
it if not there and check via that) so it will only show it 
optionally?
Feb 26 2018
parent Adam D. Ruppe <destructionator gmail.com> writes:
On Monday, 26 February 2018 at 19:30:38 UTC, WebFreak001 wrote:

 amazing! I planned on adding a documentation tab in the current 
 dub package overhaul, but I wasn't sure on where to get the 
 data from, if I can add this to embed on the dub website (ala 
 iframe) it would make a lot much easier! Could you maybe add an 
 API endpoint to check if documentation is present (download & 
 cache it if not there and check via that) so it will only show 
 it optionally?


I'd say just always show the documentation tab/link. If it is 
broken, we can tell the package maintainer to fix it!

BTW the header now has links for the project homepage (if it has 
one), dub package, and git repo

http://vibe-d.dpldocs.info/vibe.core.drivers.libevent2_tcp.html

for example.

(docs generated already will not show this until i next clear the 
internal cache. prolly tomorrow)
Feb 26 2018
prev sibling next sibling parent reply Jesse Phillips <Jesse.K.Phillips+D gmail.com> writes:
On Monday, 26 February 2018 at 14:59:07 UTC, Adam D. Ruppe wrote:


 I'd like to get the code.dlang.org folks to add the correct 
 link to the main package site so people can easily discover 
 this.... just put nofollow on it plz so google doesn't trigger 
 generation of pages people don't actually need (the lazy 
 generation + caching allows me to host this on a cheap VPS)


It also would be good for you to like to the Dub page and Git 
Repo.

Couldn't you provide a robots.txt file which Google should honor 
so that 'nofollow' isn't required?
Feb 26 2018
parent Adam D. Ruppe <destructionator gmail.com> writes:
On Monday, 26 February 2018 at 19:47:29 UTC, Jesse Phillips wrote:

 It also would be good for you to like to the Dub page and Git 
 Repo.


Yeah, its on my list. The project homepage from the dub.json too.


 Couldn't you provide a robots.txt file which Google should 
 honor so that 'nofollow' isn't required?


yeah but i don't mind them crawling pages that already exist and 
are linked from other websites where the author has agreed to 
support it somehow.
Feb 26 2018
prev sibling next sibling parent reply Antonio Corbi <antonio ggmail.com> writes:
On Monday, 26 February 2018 at 14:59:07 UTC, Adam D. Ruppe wrote:

 Many of you will already know this from the other thread or 
 from my twitter, but I just added a on-demand downloader to my 
 dpldocs.info domain to fetch and build docs for any* dub 
 package.


Hi Adam!

Thanks for this superb work!

Trying it onto gtk-d got an error saying to send you the failing 
link, so here you are :

http://gtk-d.dpldocs.info/cairo.html

A. Corbi
Feb 26 2018
parent Adam D. Ruppe <destructionator gmail.com> writes:
On Monday, 26 February 2018 at 21:16:07 UTC, Antonio Corbi wrote:

 Trying it onto gtk-d got an error saying to send you the 
 failing link, so here you are :


gtk-d is actually just too big for this, so it timed out. But I 
also already made gtkd docs on the main site:

http://dpldocs.info/experimental-docs/gtk.ApplicationWindow.ApplicationWindow.html


gtk is a bit of a special case in part because of its sheer size 
and in part because it uses C names and special gtk syntax. The 
generator can translate it though - it just needs a special 
command line arg which right now means I do it manually.
Feb 26 2018
prev sibling next sibling parent reply Norm <norm.rowtree gmail.com> writes:
On Monday, 26 February 2018 at 14:59:07 UTC, Adam D. Ruppe wrote:

 Many of you will already know this from the other thread or 
 from my twitter, but I just added a on-demand downloader to my 
 dpldocs.info domain to fetch and build docs for any* dub 
 package.

 [...]


This is really awesome. It would be really cool if this could 
feedback a coverage score to code.dlang.org that indicates the 
level of documentation in a library. Something like the % of 
functions/classes/modules that are documented and if there are 
any missing parameters/warnings during the parsing of docs.

Cheers,
Norm
Feb 26 2018
next sibling parent Adam D. Ruppe <destructionator gmail.com> writes:
On Tuesday, 27 February 2018 at 02:07:34 UTC, Norm wrote:

 This is really awesome. It would be really cool if this could 
 feedback a coverage score to code.dlang.org that indicates the 
 level of documentation in a library. Something like the % of 
 functions/classes/modules that are documented and if there are 
 any missing parameters/warnings during the parsing of docs.


Maybe, though I don't think computer analysis can say if docs are 
good (at least not with simple code I'd be likely to write). Like 
there might be a lot of public functions deliberately 
undocumented because they are of alpha quality and not supported, 
but still available in case advanced users want to dive in.

But just having docs generated automatically that users can click 
on and peruse will give the human a chance to quickly and easily 
evaluate the package.
Feb 26 2018
prev sibling parent Martin Tschierschke <mt smartdolphin.de> writes:
On Tuesday, 27 February 2018 at 02:07:34 UTC, Norm wrote:

 On Monday, 26 February 2018 at 14:59:07 UTC, Adam D. Ruppe 
 wrote:

 Many of you will already know this from the other thread or 
 from my twitter, but I just added a on-demand downloader to my 
 dpldocs.info domain to fetch and build docs for any* dub 
 package.

 [...]


 This is really awesome. It would be really cool if this could 
 feedback a coverage score to code.dlang.org that indicates the 
 level of documentation in a library. Something like the % of 
 functions/classes/modules that are documented and if there are 
 any missing parameters/warnings during the parsing of docs.

 Cheers,
 Norm


+1000 !
Feb 26 2018
prev sibling next sibling parent Jonathan M Davis <newsgroup.d jmdavisprog.com> writes:
On Monday, February 26, 2018 17:53:23 H. S. Teoh via Digitalmars-d-announce 
wrote:

 On Mon, Feb 26, 2018 at 06:43:55PM -0700, Jonathan M Davis via
 Digitalmars-d-announce wrote: [...]


 Well, then basically, projects are going to need to decide to go with
 adrdox over ddoc if they want clean documentation. They'll probably
 get better documentation with adrdox than the default ddoc if they do
 nothing, but any project that actually goes to the effort of having
 nice looking documentation is going to fall flat on its face with
 adrdox unless it buys into adrdox whole hog.

 dxml would be a prime example of a project that won't work with adrdox
 though given that it tries to emulate what Phobos has done with its
 documentation, and many of the macros are the same, which should
 minimize how much the documentation will have to be mucked with if it
 ever ends up in Phobos, but that means that it is very much not
 vanilla ddoc, let alone adrdox.


 [...]

 It's a sorry state of affairs.  I dream of the day when I can just write
 code and documentation as-is, and downstream users can just use whatever
 doc formatting system they like and it will all Just Work(tm).

 Basically, it requires a standard way of writing documentation that
 every backend tool understands and supports, be it ddoc or adrdox or
 whatever else you fancy.  But I'm not holding my breath for that to
 materialize.


Basically, it requires that you do _nothing_ by hand - so no ddoc macros -
and the tools figure it all out from the json output from the compiler. As
soon as you start marking up the documentation in any way, unless it's a way
that _all_ of the tools understand, it's not going to work. And doing
something like using macros to generate links like Phobos or dxml do is
instant death to that - the same goes with adrdox's markup for links, though
that is more automated, so it would be possible to make that understood by
more tools, whereas links for ddoc macros are too specific for that.

ddoc does a good job of doing some of the basics, and it provides a way to
have really nice documentation if you go the extra mile (including using
additional tools to generate stuff like navigation bars to navigate between
modules), but it utterly fails as a way to just generate really nice
documentation. For that, it would have to process the entire project at once
and not be file-centric like it is now. It would also have to do more for
you and leave less to macros.

Ultimately, I think that it's going to be up to each project to choose which
tool or combination of tools to use to generate their documentation, and any
time that anyone doesn't bother to figure that out, you're going to get a
subpar result - though ddox and adrdox will likely result in better
documentation with no effort than pure ddoc will, since they do stuff like
generate the navigation bar for you.

Once I've cleaned it up and documented it, I'm actually planning on
releasing what I did for dxml as project on github so that it will be
possible for anyone's project to easily have documentation like dxml does
(including the navigation bar), though like Phobos, it requires manually
using linking macros, since it's just ddoc with a helper program to generate
the pieces that you can't do with macros. If you want documentation without
any attempt to mark anything up, ddox is probably your best bet.

- Jonathan M Davis
Feb 26 2018
prev sibling next sibling parent reply bauss <jj_1337 live.dk> writes:
On Monday, 26 February 2018 at 14:59:07 UTC, Adam D. Ruppe wrote:

 Many of you will already know this from the other thread or 
 from my twitter, but I just added a on-demand downloader to my 
 dpldocs.info domain to fetch and build docs for any* dub 
 package.

 Simply go to projectname.dpldocs.info/vX.Y.Z/ and it will 
 generate docs for dub package projectname, version X.Y.Z. (If 
 you don't specify a version, it will pull the master branch.)

 For example:

 http://arsd-official.dpldocs.info/arsd.html

 master branch for the arsd-official package

 or:

 http://dplug.dpldocs.info/v6.0.22/dplug.html

 6.0.22 of the dplug package.

 etc.

 I'd like to get the code.dlang.org folks to add the correct 
 link to the main package site so people can easily discover 
 this.... just put nofollow on it plz so google doesn't trigger 
 generation of pages people don't actually need (the lazy 
 generation + caching allows me to host this on a cheap VPS)


 It builds the docs using my own doc generator 
 <https://github.com/adamdruppe/adrdox> which pulls embedded doc 
 comments out of the source.

 It isn't 100% compatible with ddoc. For example, this 
 user-defined macro was not expanded: 
 http://dxml.dpldocs.info/dxml.dom.html#source

 But, it builds 99% of Phobos so it can probably build your 
 project too! And get the ease of adrdox navigation and 
 legibility.

 Moreover, if you want to embrace it, you can use all the 
 features described here: 
 http://dpldocs.info/experimental-docs/adrdox.syntax.html except 
 for the LaTeX math generation (that's not installed on the dub 
 doc server I set up).

 You can group functions like seen here: 
 http://dpldocs.info/experimental-docs/arsd.nanovega.html and 
 use some markdown syntax, and easy [reference] linking and more.



 The generated docs may get some customization options in the 
 future, like adding a logo, header nav links, or maybe tweaking 
 the color scheme. It will probably also start reading 
 .gitignore and perhaps a .adrdoxignore file soon to to exclude 
 files from generation. I just need to decide the details first 
 and it is time to work the day job right now and I want to 
 announce sooner rather than later :)


 * currently, only github code downloading is actually 
 implemented.


Tried with http://diamond.dpldocs.info/arsd.html and it gives a 
404
Feb 27 2018
parent reply bauss <jj_1337 live.dk> writes:
On Tuesday, 27 February 2018 at 09:16:12 UTC, bauss wrote:

 On Monday, 26 February 2018 at 14:59:07 UTC, Adam D. Ruppe 
 wrote:

 [...]


 Tried with http://diamond.dpldocs.info/arsd.html and it gives a 
 404


Nvm, I see how stupid I was.
Feb 27 2018
next sibling parent aberba <karabutaworld gmail.com> writes:
On Tuesday, 27 February 2018 at 09:17:21 UTC, bauss wrote:

 On Tuesday, 27 February 2018 at 09:16:12 UTC, bauss wrote:

 On Monday, 26 February 2018 at 14:59:07 UTC, Adam D. Ruppe 
 wrote:

 [...]


 Tried with http://diamond.dpldocs.info/arsd.html and it gives 
 a 404


 Nvm, I see how stupid I was.


You were not stupid. You made a mistake. They're two different 
things.
Feb 27 2018
prev sibling parent Adam D. Ruppe <destructionator gmail.com> writes:
On Tuesday, 27 February 2018 at 09:17:21 UTC, bauss wrote:

 Nvm, I see how stupid I was.


Nah, bad UX. I give myself some slack cuz I slapped this together 
in just a few spare hours over the weekend, but the error message 
also could have pointed you back to the site index.

That just took 3 minutes to change tho, now it says:

404. Try diamond.html as a starting point (and it is a link)
Feb 27 2018
prev sibling next sibling parent reply Basile B. <b2.temp gmx.com> writes:
On Monday, 26 February 2018 at 14:59:07 UTC, Adam D. Ruppe wrote:

 Many of you will already know this from the other thread or 
 from my twitter, but I just added a on-demand downloader to my 
 dpldocs.info domain to fetch and build docs for any* dub 
 package.

 Simply go to projectname.dpldocs.info/vX.Y.Z/ and it will 
 generate docs for dub package projectname, version X.Y.Z. (If 
 you don't specify a version, it will pull the master branch.)

 For example:

 http://arsd-official.dpldocs.info/arsd.html

 master branch for the arsd-official package

 or:

 http://dplug.dpldocs.info/v6.0.22/dplug.html

 6.0.22 of the dplug package.

 etc.

 I'd like to get the code.dlang.org folks to add the correct 
 link to the main package site so people can easily discover 
 this.... just put nofollow on it plz so google doesn't trigger 
 generation of pages people don't actually need (the lazy 
 generation + caching allows me to host this on a cheap VPS)


 It builds the docs using my own doc generator 
 <https://github.com/adamdruppe/adrdox> which pulls embedded doc 
 comments out of the source.

 It isn't 100% compatible with ddoc. For example, this 
 user-defined macro was not expanded: 
 http://dxml.dpldocs.info/dxml.dom.html#source

 But, it builds 99% of Phobos so it can probably build your 
 project too! And get the ease of adrdox navigation and 
 legibility.

 Moreover, if you want to embrace it, you can use all the 
 features described here: 
 http://dpldocs.info/experimental-docs/adrdox.syntax.html except 
 for the LaTeX math generation (that's not installed on the dub 
 doc server I set up).

 You can group functions like seen here: 
 http://dpldocs.info/experimental-docs/arsd.nanovega.html and 
 use some markdown syntax, and easy [reference] linking and more.



 The generated docs may get some customization options in the 
 future, like adding a logo, header nav links, or maybe tweaking 
 the color scheme. It will probably also start reading 
 .gitignore and perhaps a .adrdoxignore file soon to to exclude 
 files from generation. I just need to decide the details first 
 and it is time to work the day job right now and I want to 
 announce sooner rather than later :)


 * currently, only github code downloading is actually 
 implemented.


Awesome work. IDEs could use this, i don't know how yet but i'll 
maybe try something one day.

Are the doc persistent on your server ?
For example is http://iz.dpldocs.info/v0.6.4/iz.html here forever 
?
Feb 27 2018
parent reply Adam D. Ruppe <destructionator gmail.com> writes:
On Tuesday, 27 February 2018 at 10:02:13 UTC, Basile B. wrote:

 Awesome work. IDEs could use this, i don't know how yet but 
 i'll maybe try something one day.


Yeah, webfreak was talking to me about that on irc and I've had 
people ask me about the main dpldocs site being an api (to which 
I reply "it is already a REST api returning a XML 
representation.... called a static html page". which i think is 
good - this html is a bit verbose bu that's because i wrote it 
with a lot of semantic information included in the tags, it can 
be machine parsed and analyzed. need a lib for it? use my dom.d 
:P )

But anyway, once I see someone with a prototype and we can 
identify specific needs through use, then I'm open to adding more 
stuff to help that effort. Until then tho my feeling is YAGNI and 
I am keeping the code on this server simple - try the IDE 
integration just showing the HTML in a web view first, or 
scraping the html for plain text, and we'll see how that looks as 
the first draft.


 Are the doc persistent on your server ?
 For example is http://iz.dpldocs.info/v0.6.4/iz.html here 
 forever ?


Logically yes, in reality, maybe but I'm in the shell right now 
`rm -r`ing from time to time as I update the generator, and then 
your page will be automatically rebuild on the next request with 
the new generator version.

But that has already stabilized quite a bit so a lot of those 
files may in fact sit there for a very long time. I may also 
clear some if i ever hit a disk space limit tho...

but in any case, if a page is requested, it will be there, even 
if it has to be unzipped/regenerated first. Just be a bit patient 
waiting for the load in those events.
Feb 27 2018
parent reply Basile B. <b2.temp gmx.com> writes:
On Tuesday, 27 February 2018 at 14:42:11 UTC, Adam D. Ruppe wrote:

 On Tuesday, 27 February 2018 at 10:02:13 UTC, Basile B. wrote:

 Awesome work. IDEs could use this, i don't know how yet but 
 i'll maybe try something one day.


 Yeah, webfreak was talking to me about that on irc and I've had 
 people ask me about the main dpldocs site being an api (to 
 which I reply "it is already a REST api returning a XML 
 representation.... called a static html page". which i think is 
 good - this html is a bit verbose bu that's because i wrote it 
 with a lot of semantic information included in the tags, it can 
 be machine parsed and analyzed. need a lib for it? use my dom.d 
 :P )

 But anyway, once I see someone with a prototype and we can 
 identify specific needs through use, then I'm open to adding 
 more stuff to help that effort.


I think that nothing more is needed.

The idea is to use DCD to get the d source where a symbol is 
declared, from this file it's possible to guess the html page for 
this symbol. Actually i already do this for phobos (using the 
official html) and it works fine.

At first glance i can say that this will work perfectly for DUB 
packages. Once DCD gives a file, the IDE just have to look the 
parent folders to get the SemVer tag.
If the file is in a git repository things might be more 
complicated.

The only difference with what is done right now (in Coedit) is 
the url structure.


While with ardrox it's <module>.<symbol>.html.
Feb 27 2018
parent Nick Sabalausky <a a.a> writes:
On Tuesday, 27 February 2018 at 15:49:37 UTC, Basile B. wrote:

 At first glance i can say that this will work perfectly for DUB 
 packages. Once DCD gives a file, the IDE just have to look the 
 parent folders to get the SemVer tag.
 If the file is in a git repository things might be more 
 complicated.


In most cases its pretty easy from a git repo too, just run 'git 
describe'. That'll give you the latest (annotated) tag (which 
SHOULD be the semver number, and generally is for dub projects) 
and no other output. Nothing to parse or scrape.

If theres been extra commits since the last tag, then there's a 
little extra suffix appended to git describe's output, but its 
trivial enough to parse/remove if you need to.
Feb 27 2018
prev sibling next sibling parent reply Jonas Drewsen <nospam4321 hotmail.com> writes:
On Monday, 26 February 2018 at 14:59:07 UTC, Adam D. Ruppe wrote:

 Many of you will already know this from the other thread or 
 from my twitter, but I just added a on-demand downloader to my 
 dpldocs.info domain to fetch and build docs for any* dub


Would be cool if you could add support for creating docs from any 
dub project stored on github and not only the ones on 
code.dlang.org.

e.g. create docs for https://github.com/anton-dutov/db:

http://githubdoc.dpldocs.info/anton-dutov/db/v6.0.22/db.html

or something like that.
Mar 01 2018
parent reply Adam D. Ruppe <destructionator gmail.com> writes:
On Thursday, 1 March 2018 at 11:00:15 UTC, Jonas Drewsen wrote:

 Would be cool if you could add support for creating docs from 
 any dub project stored on github and not only the ones on 
 code.dlang.org.


That might be possible too.


BTW I just put the server code up on github
https://github.com/adamdruppe/dpldocs


there's actually not that much to it right now.
Mar 01 2018
parent reply bauss <jj_1337 live.dk> writes:
On Friday, 2 March 2018 at 00:04:10 UTC, Adam D. Ruppe wrote:

 On Thursday, 1 March 2018 at 11:00:15 UTC, Jonas Drewsen wrote:

 Would be cool if you could add support for creating docs from 
 any dub project stored on github and not only the ones on 
 code.dlang.org.


 That might be possible too.


 BTW I just put the server code up on github
 https://github.com/adamdruppe/dpldocs


 there's actually not that much to it right now.


How would you go about updating docs?

I'd like to have http://diamond.dpldocs.info/diamond.html updated

Thank you!
Mar 07 2018
parent Adam D. Ruppe <destructionator gmail.com> writes:
On Wednesday, 7 March 2018 at 22:47:48 UTC, bauss wrote:

 How would you go about updating docs?


Either go to the url for the specific version you want like 
http://diamond.dpldocs.info/v2.7.0/index.html and it will 
download (once dub scrapes it anyway)

or ping me and I'll manually update the master branch. so this is 
good now too http://diamond.dpldocs.info/diamond.html


I still haven't decided when I want to automatically update 
master so it is manual at this point.
Mar 07 2018
prev sibling next sibling parent Adam D. Ruppe <destructionator gmail.com> writes:
If you guys have bug reports or feature requests, you can put it 
on the github too if you like:

https://github.com/adamdruppe/dpldocs/issues
Mar 01 2018
prev sibling next sibling parent reply Martin Nowak <code+news.digitalmars dawg.eu> writes:
On 02/26/2018 03:59 PM, Adam D. Ruppe wrote:

 http://dplug.dpldocs.info/v6.0.22/dplug.html
 
 6.0.22 of the dplug package.


Cool stuff Adam, thx. Was thinking about this for a while myself.
A central doc provider could have some benefit, e.g. searching across
different libraries.

Compared to how difficult it is to run such a service reliably and over
a long time, it is fairly easy to setup automatic docs on gh-pages for a
dub package.
https://forum.dlang.org/post/tkcndtapfypabsncxxla forum.dlang.org
https://github.com/wilzbach/d-bootstrap#i-want-to-have-nice-documentation-for-my-project

I maintain a blueprint repo that exemplifies how to integrate CI testing
with coverage and docs.
https://github.com/MartinNowak/bloom
https://code.dlang.org/packages/bloom

-Martin
Mar 02 2018
parent reply Adam D. Ruppe <destructionator gmail.com> writes:
On Saturday, 3 March 2018 at 02:12:52 UTC, Martin Nowak wrote:

 A central doc provider could have some benefit, e.g. searching 
 across different libraries.


Yeah, I have code for that written for select libraries already 
(on the main dpldocs.info site), but haven't opened it up to the 
full dub repo yet... I should be able to though, especially if I 
spring for the next tier of VPS.

Check this out: https://dpldocs.info/isSomeString

full-text search over a select group of packages (notably 
including Phobos) with a pretty fast response... just it eats 
~1.5 GB to keep two copies of its database in memory in order to 
give those fast responses concurrently. The instance I have 
opened up to dub has a 1 GB limit right now...

But if the patreon thing takes off, I can afford to throw more 
memory at it, and/or I could prolly optimize that search database 
too, so it will come.



 https://forum.dlang.org/post/tkcndtapfypabsncxxla forum.dlang.org


Yeah, that's not a bad solution, though what's nice about my 
solution is the author doesn't actually have to do anything... 
the user just goes to the docs and they appear!
Mar 02 2018
parent reply Martin Nowak <code+news.digitalmars dawg.eu> writes:
On 03/03/2018 04:01 AM, Adam D. Ruppe wrote:

 full-text search over a select group of packages (notably including
 Phobos) with a pretty fast response... just it eats ~1.5 GB to keep two
 copies of its database in memory in order to give those fast responses
 concurrently. The instance I have opened up to dub has a 1 GB limit
 right now...


Why would you need to have that in RAM instead of leaving it to the db
cache layer?


 But if the patreon thing takes off, I can afford to throw more memory at
 it, and/or I could prolly optimize that search database too, so it will
 come.


Where are you hosting?
https://www.hetzner.de/cloud has fairly affordable KVMs


 https://forum.dlang.org/post/tkcndtapfypabsncxxla forum.dlang.org


 
 Yeah, that's not a bad solution, though what's nice about my solution is
 the author doesn't actually have to do anything... the user just goes to
 the docs and they appear!


That's a fallacy. If one doesn't have to do anything, it means it's more
likely that nothing is done. Adding useful documentation is one of the
most important tasks when writing a library and I'd expect any library
with basic quality standards to take care of that.
Good docs and CI are good indicators for the quality and usability of a
project.

-Martin
Mar 03 2018
parent Adam D. Ruppe <destructionator gmail.com> writes:
On Saturday, 3 March 2018 at 13:17:15 UTC, Martin Nowak wrote:

 Why would you need to have that in RAM instead of leaving it to 
 the db cache layer?


The search "database" right now is an XML file. Keep in mind this 
is a static site generator meant to just work offline or when 
pushed to github pages and thus avoids dependencies on... well, 
anything. Even if the server side search program is running, it 
reuses that same xml file as it was the simplest thing that could 
possibly work. Reading the file was slow, so I kept it in memory 
with a hashtable index. And since it does a pretty good job and 
the server hosting Phobos was under no memory pressure anyway, 
I've left it to focus on other things for the last year.

So, when I say "optimize that search database" one of the options 
would be to actually use a real database layer :)


 Where are you hosting?
 https://www.hetzner.de/cloud has fairly affordable KVMs


The dub part is on a $5 digital ocean droplet right now. The 
phobos one is a spare computer in my house.



 That's a fallacy. If one doesn't have to do anything, it
 means it's more likely that nothing is done.


Empirical reality disagrees with you. Actually writing the doc 
comments is enough effort as it is and making people go through a 
12-step program to host it (or deal with ddoc's... quirks instead 
of focusing on the actual content) makes it enough of a hassle 
that plenty of people just don't bother. That's why so many dub 
packages are undocumented now.

Though since I put this up, three different people have already 
emailed me asking to delete their ~master caches because they 
added doc comments where none existed before and didn't want to 
leave the embarrassing empty page up any longer than they had to!


 Adding useful documentation is one of the most important
 tasks when writing a library and I'd expect any library with 
 basic quality standards to take care of that.


Yes, and that's why so many users are unimpressed with the 
code.dlang.org site as it was. Lots of packages with no online 
docs, and those who had them were hard to find, leading them to 
believe the whole library was trash.

Well, turns out a bunch of them DO have doc comments, they just 
aren't hosted, and among those without doc comments, they are 
willing to add them with just a bit of motivation and reduction 
of friction.

That's no changing, and it is already making a difference.
Mar 03 2018
prev sibling next sibling parent Adam D. Ruppe <destructionator gmail.com> writes:
Gtk-d and DWT are both too big to automatically build on the 
server, but I did some manual work on them.

DWT:

http://dwt.dpldocs.info/org.eclipse.swt.widgets.html

GTK-D:
http://dpldocs.info/experimental-docs/gtk.Application.Application.html


The gtk one has me translating some syntax from C to D 
automatically. I figure I'll do that kind of thing for dwt too 
eventually, so its javadoc renders a bit better too.


These two libs are bigger jobs so they won't be full featured for 
a while, but even these partial documentations are better than 
I've seen available for them before.
Mar 02 2018
prev sibling parent Colin <grogan.colin gmail.com> writes:
On Monday, 26 February 2018 at 14:59:07 UTC, Adam D. Ruppe wrote:

 Many of you will already know this from the other thread or 
 from my twitter, but I just added a on-demand downloader to my 
 dpldocs.info domain to fetch and build docs for any* dub 
 package.

 Simply go to projectname.dpldocs.info/vX.Y.Z/ and it will 
 generate docs for dub package projectname, version X.Y.Z. (If 
 you don't specify a version, it will pull the master branch.)

 For example:

 http://arsd-official.dpldocs.info/arsd.html

 master branch for the arsd-official package

 or:

 http://dplug.dpldocs.info/v6.0.22/dplug.html

 6.0.22 of the dplug package.

 etc.

 I'd like to get the code.dlang.org folks to add the correct 
 link to the main package site so people can easily discover 
 this.... just put nofollow on it plz so google doesn't trigger 
 generation of pages people don't actually need (the lazy 
 generation + caching allows me to host this on a cheap VPS)


 It builds the docs using my own doc generator 
 <https://github.com/adamdruppe/adrdox> which pulls embedded doc 
 comments out of the source.

 It isn't 100% compatible with ddoc. For example, this 
 user-defined macro was not expanded: 
 http://dxml.dpldocs.info/dxml.dom.html#source

 But, it builds 99% of Phobos so it can probably build your 
 project too! And get the ease of adrdox navigation and 
 legibility.

 Moreover, if you want to embrace it, you can use all the 
 features described here: 
 http://dpldocs.info/experimental-docs/adrdox.syntax.html except 
 for the LaTeX math generation (that's not installed on the dub 
 doc server I set up).

 You can group functions like seen here: 
 http://dpldocs.info/experimental-docs/arsd.nanovega.html and 
 use some markdown syntax, and easy [reference] linking and more.



 The generated docs may get some customization options in the 
 future, like adding a logo, header nav links, or maybe tweaking 
 the color scheme. It will probably also start reading 
 .gitignore and perhaps a .adrdoxignore file soon to to exclude 
 files from generation. I just need to decide the details first 
 and it is time to work the day job right now and I want to 
 announce sooner rather than later :)


 * currently, only github code downloading is actually 
 implemented.



A feature request: Display README.md in the package docs? A lot 
of projects have the front page with useful example or similar.

On a similar vein, a lot of projects have an examples/ folder. 
These could also be scanned and displayed (with links from types 
used back to the "real" ddoc documentation.

The examples/ section would (I imagine) be a lot harder to 
support as there's no standard in D yet, but this isn't new 
ground. Go projects regularly have Example_ functions as part of 
their testing files, that serve as useful documentation.
Mar 04 2018