Hi,

I am trying to get to grips with DDoc for documenting an application. Getting
the individual module HTML files seems to be the easy bit. The question is how
to get an index.html (or equivalent) so as to have an application level entry
point to the generated documentation.

-- 
Russel.
===========================================
Dr Russel Winder      t: +44 20 7585 2200
41 Buckmaster Road    m: +44 7770 465 077
London SW11 1EN, UK   w: www.russel.org.uk

On 9/18/20 7:41 AM, Russel Winder wrote:
> Hi,
> 
> I am trying to get to grips with DDoc for documenting an application. Getting
> the individual module HTML files seems to be the easy bit. The question is how
> to get an index.html (or equivalent) so as to have an application level entry
> point to the generated documentation.
>   
> 

You can make explicit ddoc files, and compile those along with your application.

https://dlang.org/spec/ddoc.html#using_ddoc_for_other_documentation

-Steve

On Fri, 2020-09-18 at 09:02 -0400, Steven Schveighoffer via Digitalmars-d- learn wrote:

[…]
> 
> it ddoc files, and compile those along with your application.
> 
> https://dlang.org/spec/ddoc.html#using_ddoc_for_other_documentation
> 

Any small project examples anywhere?

-- 
Russel.
===========================================
Dr Russel Winder      t: +44 20 7585 2200
41 Buckmaster Road    m: +44 7770 465 077
London SW11 1EN, UK   w: www.russel.org.uk

On 9/18/20 9:35 AM, Russel Winder wrote:
> On Fri, 2020-09-18 at 09:02 -0400, Steven Schveighoffer via Digitalmars-d-
> learn wrote:
> 
> […]
>>
>> it ddoc files, and compile those along with your
>> application.
>>
>> https://dlang.org/spec/ddoc.html#using_ddoc_for_other_documentation
>>
> 
> Any small project examples anywhere?
> 

I am also learning about ddoc generation (something that IMO could stand to be much better , ahem, documented). A nice example I've found is the libmir site:

https://www.libmir.org/
http://mir-algorithm.libmir.org/ (mir-core., mir-random., etc.)

and its documentation generation infrastructure:

https://github.com/libmir/circle-dlang

On 2020-09-18 13:41, Russel Winder wrote:
> Hi,
> 
> I am trying to get to grips with DDoc for documenting an application. Getting
> the individual module HTML files seems to be the easy bit. The question is how
> to get an index.html (or equivalent) so as to have an application level entry
> point to the generated documentation.

There's no built-in support for that. You might want to look at some other doc generating tool if those support that.

-- 
/Jacob Carlborg

On Sat, 2020-09-19 at 08:12 +0200, Jacob Carlborg via Digitalmars-d-learn wrote:
> On 2020-09-18 13:41, Russel Winder wrote:
> > Hi,
> > 
> > I am trying to get to grips with DDoc for documenting an application.
> > Getting
> > the individual module HTML files seems to be the easy bit. The question is
> > how
> > to get an index.html (or equivalent) so as to have an application level
> > entry
> > point to the generated documentation.
> 
> There's no built-in support for that. You might want to look at some other doc generating tool if those support that.

Doesn't that then make the whole DDoc system fairly useless, despite it's use in Phobos?

-- 
Russel.
===========================================
Dr Russel Winder      t: +44 20 7585 2200
41 Buckmaster Road    m: +44 7770 465 077
London SW11 1EN, UK   w: www.russel.org.uk

On Fri, 2020-09-18 at 20:22 -0400, James Blachly via Digitalmars-d-learn wrote:
> On 9/18/20 9:35 AM, Russel Winder wrote:
> > On Fri, 2020-09-18 at 09:02 -0400, Steven Schveighoffer via Digitalmars-d- learn wrote:
> > 
> > […]
> > > it ddoc files, and compile those along with your application.
> > > 
> > > https://dlang.org/spec/ddoc.html#using_ddoc_for_other_documentation
> > > 
> > 
> > Any small project examples anywhere?
> > 
> 
> I am also learning about ddoc generation (something that IMO could stand to be much better , ahem, documented). A nice example I've found is the libmir site:
> 
> https://www.libmir.org/
> http://mir-algorithm.libmir.org/ (mir-core., mir-random., etc.)
> 
> and its documentation generation infrastructure:
> 
> https://github.com/libmir/circle-dlang

Yikes. Maybe it is just a first sight thing, but if that is what is needed to handle Mir, maybe I should try and make Doxygen work for my D projects – though doxygen only works "to some extent D".

-- 
Russel.
===========================================
Dr Russel Winder      t: +44 20 7585 2200
41 Buckmaster Road    m: +44 7770 465 077
London SW11 1EN, UK   w: www.russel.org.uk

On Friday, 18 September 2020 at 13:35:05 UTC, Russel Winder wrote:
> On Fri, 2020-09-18 at 09:02 -0400, Steven Schveighoffer via Digitalmars-d- learn wrote:
>
> […]
>> 
>> it ddoc files, and compile those along with your application.
>> 
>> https://dlang.org/spec/ddoc.html#using_ddoc_for_other_documentation
>> 
>
> Any small project examples anywhere?

https://github.com/dlang/dconf.org/tree/master/2019

On Saturday, 19 September 2020 at 07:43:24 UTC, Russel Winder wrote:

> Doesn't that then make the whole DDoc system fairly useless, despite it's use in Phobos?

Yes.  The problem is that most things in D are compared with C or C++. People are praising that the built-in support for unit tests and Ddoc are the best things that have happened since sliced bread. But if you compare with C or C++ the bar isn't very high.

--
/Jacob Carlborg

On Saturday, 19 September 2020 at 07:43:24 UTC, Russel Winder wrote:

> Doesn't that then make the whole DDoc system fairly useless, despite it's use in Phobos?

If you use Dub, you can run `dub build -b ddox` and it will use Ddox to build the documentation. This will include an index page listing all modules. This will actually start a local web server to show the documentation. It's possible to generate documentation offline as well [1].

Or it should be pretty straightforward to write a simple script that iterates all D files and generates documentation. Then iterate all HTML files and output a simple index.html file.

[1] https://github.com/rejectedsoftware/ddox#generating-offline-documentation

--
/Jacob Carlborg