akka/akka-core

Directive to include reference.conf info in documentation

Open

#24,965 opened on Apr 24, 2018

View on GitHub
 (3 comments) (2 reactions) (0 assignees)Scala (13,277 stars) (3,547 forks)batch import
help wantednice-to-have (low-prio)t:docs

Description

It might be neat if we could create a paradox directive that finds the relevant entry in the reference.conf and includes it, including default value and comment. So in the .md something like

  @@reference[akka.scheduler.tick-duration]

Could automatically turn into:

akka {
  # Used to set the behavior of the scheduler.
  # Changing the default values may change the system behavior drastically so make
  # sure you know what you're doing! See the Scheduler section of the Akka
  # Documentation for more details.
  scheduler {
    # The LightArrayRevolverScheduler is used as the default scheduler in the
    # system. It does not execute the scheduled tasks on exact time, but on every
    # tick, it will run everything that is (over)due. You can increase or decrease
    # the accuracy of the execution timing by specifying smaller or larger tick
    # duration. If you are scheduling a lot of tasks you should consider increasing
    # the ticks per wheel.
    # Note that it might take up to 1 tick to stop the Timer, so setting the
    # tick-duration to a high value will make shutting down the actor system
    # take longer.
    tick-duration = 10ms
}

Contributor guide

Tech stack
scala
Domain
documentationtooling
Issue type
feature
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
3
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
1-2 days
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
stale
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
clear
Prerequisites
Knowledge of ParadoxFamiliarity with HOCON config
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
45
Research direction
The issue proposes a new Paradox directive to automatically include reference.conf entries with comments and defaults. To implement, one would need to create a custom Paradox directive (using Paradox's Java/Scala API) that reads the reference.conf file, parses the HOCON structure, and generates markdown output. Relevant files to explore include Paradox's directive examples and the Akka documentation plugin code in the repository. The existing comment thread has no additional details, so the implementation approach is open.