www.digitalmars.com         C & C++   DMDScript  

digitalmars.D.learn - Auto-generation of online documentation for my open libraries

reply Per =?UTF-8?B?Tm9yZGzDtnc=?= <per.nordlow gmail.com> writes:
I would like to setup auto-generation of online documentation for 
my public D libraries residing on Github and Gitlab.

What alternatives do I have?
Feb 23 2020
next sibling parent Per =?UTF-8?B?Tm9yZGzDtnc=?= <per.nordlow gmail.com> writes:
On Sunday, 23 February 2020 at 17:14:33 UTC, Per Nordlöw wrote:

 I would like to setup auto-generation of online documentation 
 for my public D libraries residing on Github and Gitlab.

 What alternatives do I have?


I'm thinking something like http://ddocs.org announced here 
https://forum.dlang.org/thread/weuxppabkrreaxbqqpdv forum.dlang.org.

Unfortunately http://ddocs.org seems to be down. Are there any 
mirrors up?
Feb 23 2020
prev sibling next sibling parent reply Andre Pany <andre s-e-a-p.de> writes:
On Sunday, 23 February 2020 at 17:14:33 UTC, Per Nordlöw wrote:

 I would like to setup auto-generation of online documentation 
 for my public D libraries residing on Github and Gitlab.

 What alternatives do I have?


If your Dub package is registered on code.dlang.org, this is 
automatically provided.

Example: http://code.dlang.org/packages/arsd-official
Click on the documentation link.

Beside that you can use e.g. Github Actions to create 
documentation.

Kind regards
Andre
Feb 23 2020
next sibling parent reply Per =?UTF-8?B?Tm9yZGzDtnc=?= <per.nordlow gmail.com> writes:
On Sunday, 23 February 2020 at 17:18:48 UTC, Andre Pany wrote:

 Example: http://code.dlang.org/packages/arsd-official
 Click on the documentation link.

 Beside that you can use e.g. Github Actions to create 
 documentation.

 Kind regards
 Andre


Thanks!

How do I check which dmd or dub command that is called to 
generate the docs?
Feb 23 2020
parent Paul Backus <snarwin gmail.com> writes:
On Sunday, 23 February 2020 at 17:38:35 UTC, Per Nordlöw wrote:

 On Sunday, 23 February 2020 at 17:18:48 UTC, Andre Pany wrote:

 Example: http://code.dlang.org/packages/arsd-official
 Click on the documentation link.

 Beside that you can use e.g. Github Actions to create 
 documentation.

 Kind regards
 Andre


 Thanks!

 How do I check which dmd or dub command that is called to 
 generate the docs?


They are generated using adrdox, a third-party documentation 
generator by Adam Ruppe:

https://github.com/adamdruppe/adrdox

The exact command used to generate the docs for dpldocs.info can 
be found here:

https://github.com/adamdruppe/dpldocs/blob/858e375b98883c9a46a6ff9a894f371fcfae23a0/dl.d#L301-L309
Feb 23 2020
prev sibling parent reply Per =?UTF-8?B?Tm9yZGzDtnc=?= <per.nordlow gmail.com> writes:
On Sunday, 23 February 2020 at 17:18:48 UTC, Andre Pany wrote:

 If your Dub package is registered on code.dlang.org, this is 
 automatically provided.

 Example: http://code.dlang.org/packages/arsd-official
 Click on the documentation link.

 Beside that you can use e.g. Github Actions to create 
 documentation.

 Kind regards
 Andre


I've fixed my phobos-next so that doc generation now works via

     dub build --build=docs --compiler=dmd

Is this command called only when I tag my repo with a new version?
Feb 23 2020
parent reply Per =?UTF-8?B?Tm9yZGzDtnc=?= <per.nordlow gmail.com> writes:
On Sunday, 23 February 2020 at 18:18:25 UTC, Per Nordlöw wrote:

 On Sunday, 23 February 2020 at 17:18:48 UTC, Andre Pany wrote:

 If your Dub package is registered on code.dlang.org, this is 
 automatically provided.

 Example: http://code.dlang.org/packages/arsd-official
 Click on the documentation link.

 Beside that you can use e.g. Github Actions to create 
 documentation.

 Kind regards
 Andre


 I've fixed my phobos-next so that doc generation now works via

     dub build --build=docs --compiler=dmd

 Is this command called only when I tag my repo with a new 
 version?


The error I currently get when clicking the documentation link 
https://phobos-next.dpldocs.info/ is


The project build failed. copy/paste this link to adam so he can 
fix the bug.

std.file.FileException std/file.d(379): 
/dpldocs/phobos-next/master/adrdox-generated/: Is a directory
----------------
/home/me/d/dmd2/linux/bin64/../../src/phobos/std/file.d:273 
 trusted bool std.file.cenforce!(bool).cenforce(bool, scope 
const(char)[], scope const(char)*, immutable(char)[], ulong) 
[0x543266]
??:?  trusted void[] std.file.readImpl(scope const(char)[], scope 
const(char)*, ulong) [0x5ec90b]
/home/me/d/dmd2/linux/bin64/../../src/phobos/std/file.d:310  safe 
void[] std.file.read!(immutable(char)[]).read(immutable(char)[], 
ulong) [0x543041]
dl.d:271 void dl.app(arsd.cgi.Cgi) [0x528000]
/home/me/arsd/cgi.d:3815 void 
arsd.cgi.doThreadScgiConnection!(arsd.cgi.Cgi, 
dl.app(arsd.cgi.Cgi), 
5000000L).doThreadScgiConnection(std.socket.Socket) [0x546e43]
/home/me/arsd/cgi.d:4361 void arsd.cgi.ConnectionThread.run() 
[0x53b2a8]
??:? void core.thread.Thread.run() [0x5c8a25]
??:? thread_entryPoint [0x6159cb]
??:? [0x7f0c425e76da]
Feb 23 2020
parent reply Adam D. Ruppe <destructionator gmail.com> writes:
On Sunday, 23 February 2020 at 18:20:19 UTC, Per Nordlöw wrote:

 The error I currently get when clicking the documentation link 
 https://phobos-next.dpldocs.info/ is


try it now.

I've been tweaking the time out and retry numbers lately so it is 
less likely to do this but still sometimes does when it 
regenerates...

but still that particular error you saw indicates i messed up an 
if condition somewhere, that path is supposed to be impossible. 
oops.

regardless it works now and you can see some of the new style 
tweaks I've been doing!
Feb 23 2020
parent Per =?UTF-8?B?Tm9yZGzDtnc=?= <per.nordlow gmail.com> writes:
On Sunday, 23 February 2020 at 18:40:03 UTC, Adam D. Ruppe wrote:

 The error I currently get when clicking the documentation link 
 https://phobos-next.dpldocs.info/ is


 try it now.

 I've been tweaking the time out and retry numbers lately so it 
 is less likely to do this but still sometimes does when it 
 regenerates...

 but still that particular error you saw indicates i messed up 
 an if condition somewhere, that path is supposed to be 
 impossible. oops.

 regardless it works now and you can see some of the new style 
 tweaks I've been doing!


Wonderful!

Thanks
Feb 23 2020
prev sibling parent Basile B. <b2.temp gmx.com> writes:
On Sunday, 23 February 2020 at 17:14:33 UTC, Per Nordlöw wrote:

 I would like to setup auto-generation of online documentation 
 for my public D libraries residing on Github and Gitlab.

 What alternatives do I have?


for gitlab they have a system of pages that's quite easy to setup:

something like

.gitlab-ci.yml
---
#to get dmd and dub
image: dlang2/dmd-ubuntu

#special section to generate gitlab "pages"
pages:
   before_script:
   - apt-get install -y <some software...>
   - <more commands to download a doc generator for ex...>
   script:
   - <command to generate the doc in "public" subfolder>
   artifacts:
     paths:
     - public
   only:
   - master
   - <other branch...>
---

and then your doc is online and updated for each push.
It can be downloaded from the artifacts too, maybe in an 
automated way I think, but havent used this for now so cant say.
Feb 23 2020