Re: Documentation for any* dub package, any version

[Adam D. Ruppe via Digitalmars-d-announce]

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.

Re: Documentation for any* dub package, any version

[bauss via Digitalmars-d-announce]

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!

Re: Documentation for any* dub package, any version

[Adam D. Ruppe via Digitalmars-d-announce]

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.

Re: Documentation for any* dub package, any version

[Martin Nowak via Digitalmars-d-announce]

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/tkcndtapfypabsncx...@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

Re: Documentation for any* dub package, any version

[Adam D. Ruppe via Digitalmars-d-announce]

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.

Re: Documentation for any* dub package, any version

[Adam D. Ruppe via Digitalmars-d-announce]

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/tkcndtapfypabsncx...@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!

Re: Documentation for any* dub package, any version

[Martin Nowak via Digitalmars-d-announce]

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/tkcndtapfypabsncx...@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

Re: Documentation for any* dub package, any version

[Adam D. Ruppe via Digitalmars-d-announce]

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

Re: Documentation for any* dub package, any version

[Adam D. Ruppe via Digitalmars-d-announce]

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.

Re: Documentation for any* dub package, any version

[Jonas Drewsen via Digitalmars-d-announce]

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.

Re: Documentation for any* dub package, any version

[Nick Sabalausky via Digitalmars-d-announce]

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.

Re: Documentation for any* dub package, any version

[David Gileadi via Digitalmars-d-announce]

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!

Re: Documentation for any* dub package, any version

[David Gileadi via Digitalmars-d-announce]

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."

Re: Documentation for any* dub package, any version

[Adam D. Ruppe via Digitalmars-d-announce]

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.

Re: Documentation for any* dub package, any version

[David Gileadi via Digitalmars-d-announce]

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

Re: Documentation for any* dub package, any version

[Adam D. Ruppe via Digitalmars-d-announce]

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 [].

Re: Documentation for any* dub package, any version

[David Gileadi via Digitalmars-d-announce]

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.

Re: Documentation for any* dub package, any version

[Basile B. via Digitalmars-d-announce]

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.
For now it's  ".html#" or 
"_.html#".

While with ardrox it's ..html.

Re: Documentation for any* dub package, any version

[Adam D. Ruppe via Digitalmars-d-announce]

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.

Re: Documentation for any* dub package, any version

[Adam D. Ruppe via Digitalmars-d-announce]

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)

Re: Documentation for any* dub package, any version

[Basile B. via Digitalmars-d-announce]

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 
 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 
?

Re: Documentation for any* dub package, any version

[aberba via Digitalmars-d-announce]

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.

Re: Documentation for any* dub package, any version

[bauss via Digitalmars-d-announce]

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.

Re: Documentation for any* dub package, any version

[bauss via Digitalmars-d-announce]

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 
 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

Re: Documentation for any* dub package, any version

[Martin Tschierschke via Digitalmars-d-announce]

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 !

Re: Documentation for any* dub package, any version

[H. S. Teoh via Digitalmars-d-announce]

On Tue, Feb 27, 2018 at 03:07:10AM +, 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

Re: Documentation for any* dub package, any version

[Adam D. Ruppe via Digitalmars-d-announce]

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)

Re: Documentation for any* dub package, any version

[psychoticRabbit via Digitalmars-d-announce]

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!

Re: Documentation for any* dub package, any version

[Adam D. Ruppe via Digitalmars-d-announce]

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!

Re: Documentation for any* dub package, any version

[Jonathan M Davis via Digitalmars-d-announce]

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

Re: Documentation for any* dub package, any version

[Adam D. Ruppe via Digitalmars-d-announce]

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.

Re: Documentation for any* dub package, any version

[Adam D. Ruppe via Digitalmars-d-announce]

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:
http://jmdavisprog.com/docs/dxml/0.2.3/dxml_dom.html#.DOMEntity

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:
http://jmdavisprog.com/docs/dxml/0.2.3/dxml_parser.html#.EntityType.elmentStart

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:
http://jmdavisprog.com/docs/dxml/0.2.3/dxml_util.html#.asNormalized

"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.

Re: Documentation for any* dub package, any version

[Jonathan M Davis via Digitalmars-d-announce]

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

Re: Documentation for any* dub package, any version

[Norm via Digitalmars-d-announce]

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

Re: Documentation for any* dub package, any version

[H. S. Teoh via Digitalmars-d-announce]

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

Re: Documentation for any* dub package, any version

[Jonathan M Davis via Digitalmars-d-announce]

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

Re: Documentation for any* dub package, any version

[Adam D. Ruppe via Digitalmars-d-announce]

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.

Re: Documentation for any* dub package, any version

[Antonio Corbi via Digitalmars-d-announce]

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

Re: Documentation for any* dub package, any version

[Adam D. Ruppe via Digitalmars-d-announce]

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.

Re: Documentation for any* dub package, any version

[aliak via Digitalmars-d-announce]

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

Re: Documentation for any* dub package, any version

[Adam D. Ruppe via Digitalmars-d-announce]

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.)

Re: Documentation for any* dub package, any version

[Adam D. Ruppe via Digitalmars-d-announce]

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.

Re: Documentation for any* dub package, any version

[Jesse Phillips via Digitalmars-d-announce]

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?

Re: Documentation for any* dub package, any version

[WebFreak001 via Digitalmars-d-announce]

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?

Re: Documentation for any* dub package, any version

[Adam D. Ruppe via Digitalmars-d-announce]

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.

Re: Documentation for any* dub package, any version

[Jonathan M Davis via Digitalmars-d-announce]

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

Re: Documentation for any* dub package, any version

[aliak via Digitalmars-d-announce]

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 
 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

Re: Documentation for any* dub package, any version

[Guillaume Piolat via Digitalmars-d-announce]

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?

Documentation for any* dub package, any version

[Adam D. Ruppe via Digitalmars-d-announce]

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 
 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.