Extended help generation

[MilesCranmer]

Hey @rafaqz,

I was wondering if there was a way to generate "Extended help" documentation for an interface? As described in https://docs.julialang.org/en/v1/manual/documentation/#Writing-Documentation there is this special # Extended help trigger:

For long docstrings, consider splitting the documentation with an # Extended help header. The typical help-mode will show only the material above the header; you can access the full help by adding a '?' at the beginning of the expression (i.e., "??foo" rather than "?foo").

I think this would be useful for very long interfaces. For example, DynamicExpressions.ExpressionInterface has 20 functions to implement (implementation here), including the optional ones. I could see this being overwhelming for someone to go look up each of the docstrings for each, so I'm wondering if maybe the generated docs for an interface could include all the component descriptions?

Right now, the help (with a single ?):

help?> DynamicExpressions.NodeInterface
      NodeInterface

  An Interfaces.jl Interface with mandatory components (:create_node, :copy, :hash, :any, :equality, :preserve_sharing, :constructorof, :eltype, :with_type_parameters, :default_allocator,
  :set_node!, :count_nodes, :tree_mapreduce) and optional components (:leaf_copy, :leaf_hash, :leaf_equal, :branch_copy, :branch_hash, :branch_equal, :count_depth, :is_node_constant,
  :count_constants, :filter_map, :has_constants, :get_constants, :set_constants!, :index_constants, :has_operators).

  Defines the interface for AbstractExpressionNode which can include various operations such as copying, hashing, and checking equality, as well as tree-specific operations like
  map-reduce and node manipulation.

is the same as extended help (double ??):

help?> ?DynamicExpressions.NodeInterface
      NodeInterface

  An Interfaces.jl Interface with mandatory components (:create_node, :copy, :hash, :any, :equality, :preserve_sharing, :constructorof, :eltype, :with_type_parameters, :default_allocator,
  :set_node!, :count_nodes, :tree_mapreduce) and optional components (:leaf_copy, :leaf_hash, :leaf_equal, :branch_copy, :branch_hash, :branch_equal, :count_depth, :is_node_constant,
  :count_constants, :filter_map, :has_constants, :get_constants, :set_constants!, :index_constants, :has_operators).

  Defines the interface for AbstractExpressionNode which can include various operations such as copying, hashing, and checking equality, as well as tree-specific operations like
  map-reduce and node manipulation.

I think the extended help could be a good chance to include all component descriptions. What do you think?

Cheers,
Miles

[rafaqz]

Sure sounds good. Could we just add another argument to the macro?

A PR would be great

[MilesCranmer]

Done! In #47

[MilesCranmer]

Thanks for merging! Could you also publish a new release so I can use this wonderful new feature? 🙂

[MilesCranmer]

(I see the patch bump – thanks! Do you think you could trigger registrator?)

[rafaqz]

Sorry I'm on the road all week and cant comment on commits from my phone. But I should have a laptop open later tonight.

[MilesCranmer]

No worries!

(If you can't click the commit, here's the link: e0243ed https://github.com/rafaqz/Interfaces.jl/commit/e0243ed953aa7d7ac302bd63449e37667e791262 😁 )

[rafaqz]

Done!! (the github app just doesn't allow commenting on commits, no idea why... and my phone also forces all github urls to the app)

[MilesCranmer]

Awesome, cheers! 🍺