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.

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

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

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!

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.

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

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.

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.

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!

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.