如何通过Dub --build=ddoc用原生DDoc生成符号列表？

Great question! The short answer is yes—you absolutely can build that familiar "Jump to:" symbol list using only native DDoc, no external tools like ddox or JavaScript required, and zero manual link maintenance. Here's how to replicate Phobos' approach with DDoc's built-in macros and template system:

Step 1: Create a Custom DDoc Template #

DDoc lets you define reusable templates that control how your documentation is rendered. Create a file (e.g., phobos-style.ddoc) with the following content to add the jump section and style it to match Phobos' clean look:

// Add custom styling for the jump section
$(STYLE
  .jump-container {
    margin: 1.5em 0;
    padding: 0.75em;
    background-color: #f8f9fa;
    border-radius: 6px;
    border: 1px solid #e9ecef;
  }
  .jump-container ul {
    list-style: none;
    padding-left: 0;
    display: inline;
    margin-left: 0.5em;
  }
  .jump-container li {
    display: inline-block;
    margin-right: 1.25em;
  }
  .jump-container a {
    text-decoration: none;
    color: #007acc;
  }
  .jump-container a:hover {
    text-decoration: underline;
  }
)

// Main header + Jump to section
$(HEADER1 $(MODULE))

$(DIV class="jump-container")
$(B Jump to:)
$(UL
  // List all functions
  $(foreach func, $(FUNCTIONS)
    $(LI $(LINK $(func), $(func)))
  )
  // List all classes
  $(foreach cls, $(CLASSES)
    $(LI $(LINK $(cls), $(cls)))
  )
  // List all structs
  $(foreach s, $(STRUCTS)
    $(LI $(LINK $(s), $(s)))
  )
  // Add other symbol types as needed: ENUMS, ALIASES, etc.
)
$(DIV)

// Include the rest of the documentation content
$(CONTENTS)

Step 2: Use the Template with Dub #

When building your documentation with Dub, specify your custom template using the --ddoc-file flag:

dub --build=ddoc --ddoc-file=phobos-style.ddoc

How It Works #

• Automatic Symbol Collection: DDoc automatically scans your module for documented symbols (marked with /** ... */ comments) and exposes them via dedicated macros like $(FUNCTIONS), $(CLASSES), $(STRUCTS), and $(SYMBOLS) (for all symbols).
• Auto-Generated Anchors: Every symbol's documentation section gets an auto-generated anchor tag (e.g., #mymodule.MyFunction). The $(LINK) macro creates a direct link to these anchors without you having to write any URLs manually.
• Customizable Styling: The embedded CSS mimics Phobos' compact jump list, but you can tweak the styles to match your project's design.

Fine-Tuning #

• Filter Symbols: If you want to exclude certain symbol types or only include specific ones, just remove or add the corresponding $(foreach) blocks (e.g., remove $(ENUMS) if you don't want enums in the jump list).
• Group Symbols: For better organization (like Phobos does), you can split the jump list into labeled sections:

  $(DIV class="jump-container")
  $(B Jump to:)
  $(UL)
    $(LI $(B Functions:))
    $(foreach func, $(FUNCTIONS)
      $(LI $(LINK $(func), $(func)))
    )
    $(LI $(B Classes:))
    $(foreach cls, $(CLASSES)
      $(LI $(LINK $(cls), $(cls)))
    )
  $(/UL)
  $(/DIV)
  

This approach keeps your documentation maintenance low—DDoc handles all the link generation and symbol listing automatically, just like Phobos' docs.

内容的提问来源于stack exchange，提问作者WebFreak001