www.digitalmars.com         C & C++   DMDScript  

digitalmars.D.learn - DDoc Reference Links point to /docs/docs instead of /docs?

reply Vijay Nayar <madric gmail.com> writes:
Greetings everyone,

I have a question regarding the use of [relative 
links](https://dlang.org/spec/ddoc.html#reference_links) in DDoc. 
According to the specification, you can include a reference to an 
object that is in scope using square brackets, e.g. `[Object]`.

One of my current projects is to add support to 
[Avro](https://avro.apache.org/docs/current/index.html) in D, and 
I encountered something unusual. Consider the following code 
snippets.

```d
// File: source/avro/parser.d
module avro.parser;
class Parser {
   /// Builds a [Schema] using a path to a ".avsc" file.
   public Schema parseFile(string fileName) {
     // ...
   }
```

```d
// File: source/avro/schema.d
module avro.schema;
class Schema {
   // ...
}
```

When I build the documentation using `dub build -b docs`, which 
creates a bunch of individual `.html` files under the `docs` 
folder, but there is no `index.html` or anything else. I start by 
browsing to `file:///home/vnayar/projects/avro-d/docs/parser.html`

The documentation for the `Parser::parseFile` creates a link like 
so:
```html
<!-- File: docs/parser.html -->
<div class="ddoc_decl">
   <section class="section ddoc_sections">
   <div class="ddoc_summary">
   <p class="para">
     Builds a <a href="docs/schema.html#Schema"><code 
class="code">Schema</code></a> using a path to a ".avsc" file.
   </p>
</div>
```

However, when I click the `Schema` link in my browser, the 
relative link of `docs/schema.html` actually is relative to the 
current file, thus, it takes me to 
`file:///home/vnayar/projects/avro-d/docs/docs/schema.html#Schema`. Because the
folder `docs/docs` does not exist, I just get a file-not-found error.

Am I using DDocs incorrectly?
Feb 21 2022
parent reply Adam D Ruppe <destructionator gmail.com> writes:
tbh ddoc is pretty bad, you should try my `dub run adrdox` 
instead which also creates html but its links actually work.
Feb 21 2022
parent reply Vijay Nayar <madric gmail.com> writes:
On Monday, 21 February 2022 at 13:18:01 UTC, Adam D Ruppe wrote:

 tbh ddoc is pretty bad, you should try my `dub run adrdox` 
 instead which also creates html but its links actually work.


I gave it a try and I must say that the documentation is 
formatted in a very good way, and as you said, all the links 
work. I'm a bit surprised I've never heard of `adrdox` before 
now. Thank you kindly for that!

Regarding ddoc, should I submit a bug report? If so, is ddoc 
considered part of the compiler?
Feb 21 2022
parent reply Adam D Ruppe <destructionator gmail.com> writes:
On Monday, 21 February 2022 at 15:35:41 UTC, Vijay Nayar wrote:

 I'm a bit surprised I've never heard of `adrdox` before now.


yeah i don't advertise much. it is what runs on my dpldocs.info 
website though which auto-generates docs for dub packages.


 Regarding ddoc, should I submit a bug report? If so, is ddoc 
 considered part of the compiler?


Yeah, it is part of dmd, so you can file on issues.dlang.org if 
you want.
Feb 21 2022
parent Vijay Nayar <madric gmail.com> writes:
On Monday, 21 February 2022 at 16:58:43 UTC, Adam D Ruppe wrote:

 On Monday, 21 February 2022 at 15:35:41 UTC, Vijay Nayar wrote:

 I'm a bit surprised I've never heard of `adrdox` before now.


 yeah i don't advertise much. it is what runs on my dpldocs.info 
 website though which auto-generates docs for dub packages.


 Regarding ddoc, should I submit a bug report? If so, is ddoc 
 considered part of the compiler?


 Yeah, it is part of dmd, so you can file on issues.dlang.org if 
 you want.


Bug reported here: https://issues.dlang.org/show_bug.cgi?id=22803
Feb 21 2022