www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - Cross-platform documentation

reply Jacob Carlborg <doob me.com> writes:
Currently the documentation for Phobos and druntime is generated on (I'm 
guessing) Linux. This can sometimes cause problems when platform 
specific declarations are removed due to them not being available on 
Linux. Sometimes it looks even worse when none of the declarations are 
available on Linux [1].

How feasible would it be to generate cross-platform documentation by 
generating the docs on all platforms. For a given module, diff the all 
versions generated by the different platforms. If there's a difference, 
generate a button for each version. The button will show the 
documentation for that particular platform.

[1] http://dlang.org/phobos/core_attribute.html

-- 
/Jacob Carlborg
May 31 2016
next sibling parent reply ZombineDev <petar.p.kirov gmail.com> writes:
On Tuesday, 31 May 2016 at 07:12:06 UTC, Jacob Carlborg wrote:

 Currently the documentation for Phobos and druntime is 
 generated on (I'm guessing) Linux. This can sometimes cause 
 problems when platform specific declarations are removed due to 
 them not being available on Linux. Sometimes it looks even 
 worse when none of the declarations are available on Linux [1].

 How feasible would it be to generate cross-platform 
 documentation by generating the docs on all platforms. For a 
 given module, diff the all versions generated by the different 
 platforms. If there's a difference, generate a button for each 
 version. The button will show the documentation for that 
 particular platform.

 [1] http://dlang.org/phobos/core_attribute.html


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.
May 31 2016
parent reply Jacob Carlborg <doob me.com> writes:
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.

-- 
/Jacob Carlborg
May 31 2016
parent ZombineDev <petar.p.kirov gmail.com> writes:
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.
May 31 2016
prev sibling next sibling parent Meta <jared771 gmail.com> writes:
On Tuesday, 31 May 2016 at 07:12:06 UTC, Jacob Carlborg wrote:

 Currently the documentation for Phobos and druntime is 
 generated on (I'm guessing) Linux. This can sometimes cause 
 problems when platform specific declarations are removed due to 
 them not being available on Linux. Sometimes it looks even 
 worse when none of the declarations are available on Linux [1].

 How feasible would it be to generate cross-platform 
 documentation by generating the docs on all platforms. For a 
 given module, diff the all versions generated by the different 
 platforms. If there's a difference, generate a button for each 
 version. The button will show the documentation for that 
 particular platform.

 [1] http://dlang.org/phobos/core_attribute.html


I just ran into this yesterday wondering why the official 
documentation doesn't list any of the Windows stuff, then it hit 
me. It's definitely annoying.
May 31 2016
prev sibling parent reply Adam D. Ruppe <destructionator gmail.com> writes:
On Tuesday, 31 May 2016 at 07:12:06 UTC, Jacob Carlborg wrote:

 Currently the documentation for Phobos and druntime is 
 generated on (I'm guessing) Linux.


This is another one of the reasons why I made my own doc 
generator.

Compare:

http://dpldocs.info/core.attribute

You can see it not only saw the declaration, it knew it was in a 
version block and added that to the doc page.
May 31 2016
parent reply Jacob Carlborg <doob me.com> writes:
On 2016-05-31 16:08, Adam D. Ruppe wrote:


 This is another one of the reasons why I made my own doc generator.

 Compare:

 http://dpldocs.info/core.attribute

 You can see it not only saw the declaration, it knew it was in a version
 block and added that to the doc page.


Ah, cool.

I see that the example is not indented properly. Is that a bug in your 
tool or is that how example is written. I don't think I actually 
generated the documentation to look at the result.

-- 
/Jacob Carlborg
May 31 2016
parent Adam D. Ruppe <destructionator gmail.com> writes:
On Tuesday, 31 May 2016 at 15:01:22 UTC, Jacob Carlborg wrote:

 I see that the example is not indented properly. Is that a bug 
 in your tool or is that how example is written.


I think it is a bit of both... the leading * on the comment 
confused my indent, so basically my bug.


 I don't think I actually generated the documentation to look at 
 the result.


Yeah, you did have a broken list (in ddoc with UL and LI, you do 
NOT want commas between the LI items. on mine though i just 
translated it to markdown-esque syntax.)
May 31 2016