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.

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?

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

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

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.

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?

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?

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

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.

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