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
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
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
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
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
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
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
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
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
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: 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.
Feb 26
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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. For now it's "<module>.html#<symbol>" or "<package>_<module>.html#<symbol>". While with ardrox it's <module>.<symbol>.html.
Feb 27
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
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
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
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
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
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
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
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
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
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
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
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