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.
