digitalmars.D.learn - DDoc Reference Links point to /docs/docs instead of /docs?
- Vijay Nayar (47/47) Feb 21 2022 Greetings everyone,
- Adam D Ruppe (2/2) Feb 21 2022 tbh ddoc is pretty bad, you should try my `dub run adrdox`
- Vijay Nayar (7/9) Feb 21 2022 I gave it a try and I must say that the documentation is
- Adam D Ruppe (5/8) Feb 21 2022 yeah i don't advertise much. it is what runs on my dpldocs.info
- Vijay Nayar (2/10) Feb 21 2022 Bug reported here: https://issues.dlang.org/show_bug.cgi?id=22803
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
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
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
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
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:Bug reported here: https://issues.dlang.org/show_bug.cgi?id=22803I'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