Cross-platform documentation

[ZombineDev via Digitalmars-d]

On Tuesday, 31 May 2016 at 11:47:48 UTC, Jacob Carlborg wrote:
> On 2016-05-31 09:19, ZombineDev wrote:
>
>> The idiom is to use version (CoreDdoc) for druntime or version 
>> (StdDdoc)
>> for Phobos and to put inside declarations that you want to be 
>> visible in
>> all documentation builds. And then use version (SomePlatform) 
>> for the
>> actual definitions.
>
> The downside with that is that the declarations need to be 
> duplicated and you don't see which declarations are available 
> for which platforms.
>
> The approach I suggested, if it works, does not require to do 
> anything special.

Yeah, I know it's not optimal. I was just pointing this, in case 
you weren't aware.

Your idea is definitely an improvement. It's not unfeasible, but 
it's not that trivial either. I have some ideas about how to 
implement it:

1) Allow https://github.com/dlang/dmd/blob/master/src/doc.d to 
see all definitions, regardless if they're available only for 
certain versions. While the documentation for a module is 
generated, the lists of declarations from all versions are merged 
together with the non-versioned declarations. Some additional 
post-processing is used to provide diffs between different 
versions.

2) Use ddox + libdparse to achieve 1). It maybe easier, because 
libdparse should be able to give you the code in all versions + 
work with it may be easier than with ddmd.

3) Compile the documentation for every platform (this may require 
some cross-compilation support) and then manually perform 
post-processing.

4) Use a service like TravisCI and AppVeyor to build the docs on 
different platforms in an automated fashion and somehow collect 
the results.