[PATCH 2 of 4 V2] progress: move config help into core config help

[Gregory Szorc]

On Thu, Jun 11, 2015 at 12:23 AM, Pierre-Yves David <
pierre-yves.david at ens-lyon.org> wrote:

>
>
> On 06/10/2015 11:01 PM, Gilles Moris wrote:
>
>> Le 10/06/2015 21:02, Pierre-Yves David a écrit :
>>
>>> # HG changeset patch
>>> # User Pierre-Yves David <pierre-yves.david at fb.com>
>>> # Date 1433962615 25200
>>> #      Wed Jun 10 11:56:55 2015 -0700
>>> # Node ID 00e625c98575d0e6c93b57faaf741093285fd4b5
>>> # Parent  f81552058c8b90a5caca16aebe7fc2cb6de2d837
>>> progress: move config help into core config help
>>>
>>> This is core feature now.
>>>
>>> diff --git a/hgext/progress.py b/hgext/progress.py
>>> --- a/hgext/progress.py
>>> +++ b/hgext/progress.py
>>> @@ -9,32 +9,10 @@
>>>   This extension uses the progress information logged by hg commands
>>>   to draw progress bars that are as informative as possible. Some
>>> progress
>>>   bars only offer indeterminate information, while others have a definite
>>>   end point.
>>> -
>>> -The following settings are available::
>>> -
>>> -  [progress]
>>> -  delay = 3 # number of seconds (float) before showing the progress bar
>>> -  changedelay = 1 # changedelay: minimum delay before showing a new
>>> topic.
>>> -                  # If set to less than 3 * refresh, that value will
>>> -                  # be used instead.
>>> -  refresh = 0.1 # time in seconds between refreshes of the progress bar
>>> -  format = topic bar number estimate # format of the progress bar
>>> -  width = <none> # if set, the maximum width of the progress information
>>> -                 # (that is, min(width, term width) will be used)
>>> -  clear-complete = True # clear the progress bar after it's done
>>> -  disable = False # if true, don't show a progress bar
>>> -  assume-tty = False # if true, ALWAYS show a progress bar, unless
>>> -                     # disable is given
>>> -
>>> -Valid entries for the format field are topic, bar, number, unit,
>>> -estimate, speed, and item. item defaults to the last 20 characters of
>>> -the item, but this can be changed by adding either ``-<num>`` which
>>> -would take the last num characters, or ``+<num>`` for the first num
>>> -characters.
>>>   """
>>>   def uisetup(ui):
>>>       if ui.config('progress', 'disable', None) is None:
>>>           ui.setconfig('progress', 'disable', 'False', 'hgext-progress')
>>> diff --git a/mercurial/help/config.txt b/mercurial/help/config.txt
>>> --- a/mercurial/help/config.txt
>>> +++ b/mercurial/help/config.txt
>>> @@ -1212,10 +1212,48 @@ profiling is done using lsprof.
>>>       Show at most this number of lines of drill-down info after each
>>> main entry.
>>>       This can help explain the difference between Total and Inline.
>>>       Specific to the ``ls`` instrumenting profiler.
>>>       Default: 5.
>>> +``progress``
>>> +------------
>>> +
>>> +Mercurial hg commands can draw progress bars that are as informative as
>>> +possible. Some progress bars only offer indeterminate information,
>>> while others
>>> +have a definite end point.
>>>
>>
>> We lost the default values for all those config knob.
>> I think we should keep them.
>>
>
> Hum true.
>
> That's probably a maintenance nightmare to put them in the doc but having
> them displayed somewhere is important, so I guess that the doc is the best
> place.


This touches on existing problems with config option documentation:

* Config options for extensions don't get documented in `hg help config`
(only in the help for an extension)
* It is easy to add config options without documenting them

I'm generally interested in making docs/help suck less. One idea I had was
to declare config options using decorators/functions. e.g.

@config('histedit', 'defaultrev')
def defaultrev():
    """The default revision to use for ``hg histedit``.

    ``hg histedit`` requires a revision argument. When this option is
defined,
    its value will be used when no option is provided on the command
invocation.
    """

"Strong typing" of config options could open the door to some interesting
possibilities:

* Having config option functions validate seen values. If there are
multiple use sites, we only have to write the validation code once instead
of potentially at every use site.
* Error if an undocumented config option is looked up (probably from tests
only - at least initially - but better than nothing)
* Removing typing from lookups. If config options declare their types,
ui.config() can do the right thing and callers don't need to be bothered
with configbool(), configint(), etc.

I concede that decorators and functions may seem a bit heavyweight for
declaring options. And, loading all the Python modules just to display "hg
help config" seems like a step in the wrong direction. I'm open to other
ideas for solving the problems outlined above.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://selenic.com/pipermail/mercurial-devel/attachments/20150613/0b1a8d14/attachment.html>