Edgewall Software

Opened 13 years ago

Closed 13 years ago

Last modified 9 years ago

#9836 closed enhancement (fixed)

Describe trac.ini sections in code — at Version 8

Reported by: Remy Blank Owned by: Remy Blank
Priority: high Milestone: 1.0
Component: general Version: 0.13dev
Severity: normal Keywords:
Cc: Branch:
Release Notes:

TracIni config sections are now documented, in addition to individual configuration items

API Changes:

config: Added the ConfigSection descriptor to define and document configuration sections. [10341]

Internal Changes:

Description

Configuration options are described in the code (using Option descriptors and subclasses). It would be nice to be able to add a description for complete sections, to be rendered by the [[TracIni]] macro after the section title. This would also allow documenting sections where no explicit options are defined, like [ticket-custom].

Change History (11)

by Remy Blank, 13 years ago

Attachment: 9836-config-section-doc-r10324.patch​ added

Add descriptions to TracIni sections.

comment:1 by Remy Blank, 13 years ago

9836-config-section-doc-r10324.patch​ shows what I have in mind. I have copied the documentation from TracIni.

Thoughts?

comment:2 by Christian Boos, 13 years ago

Very cool! Something I wanted to do since a long time…

There's still the [milestone-groups] and [svn:externals] sections or did you want to leave those in the TracIni for some reason?

in reply to:  2 comment:3 by Remy Blank, 13 years ago

Replying to cboos:

There's still the [milestone-groups] and [svn:externals] sections or did you want to leave those in the TracIni for some reason?

No, I just wanted to show a few examples. I'll do the rest (and also add [intertrac], which was missing) now that I have your feedback :)

comment:4 by Sebastian Krysmanski <sebastian@…>, 13 years ago

Cc: sebastian@… added

by Remy Blank, 13 years ago

Attachment: 9836-config-section-doc-r10339.patch​ added

Full patch containing all the spectial sections from TracIni.

by Remy Blank, 13 years ago

Attachment: 9836-use-section-desc.patch​ added

Actually use the section descriptors.

comment:5 by Remy Blank, 13 years ago

9836-config-section-doc-r10339.patch​ contains all the special sections described separately in TracIni. I need feedback on two cosmetic issues before I can apply it:

  • Currently all section descriptor instances have a _section suffix. Should we keep that, or just strip the suffix and name the descriptors the same as the section (as we do for options)?
  • When accessing the descriptor on an instance, the corresponding Section object is returned. 9836-use-section-desc.patch​ actually uses this functionality, and replaces the corresponding self.config['section'] with accesses to the descriptor. Good or not?

comment:6 by Christian Boos, 13 years ago

I like using the Section instances directly from the descriptor. As for the naming, section names are usually very short which contrasts with most of the option names, so adding a _section suffix helps for readability, IMO.

comment:7 by Remy Blank, 13 years ago

API Changes: modified (diff)
Resolution: → fixed
Status: new → closed

Thanks for the feedback. Full patch applied in [10341].

comment:8 by Alex Willmer <al.willmer@…>, 12 years ago

Release Notes: modified (diff)
Note: See TracTickets for help on using tickets.