Improving DocStrings

We want to be able to hide text until hg --verbose help is used. When showing verbose text, we want subtitles. And we might want to move the options list to be able to more easily talk about them in subsequent explanatory text.

Here's what such a docstring might look like:

def pull(ui, repo, source="default", **opts):
    """pull changes from the specified source

    Pull changes from a remote repository to a local one.

    This finds all changes from the repository at the specified path
    or URL and adds them to the local repository. By default, this
    does not update the copy of the project in the working directory.
    [[[
    Examples:
    
      hg pull my/other/repo
      hg pull -u http://selenic.com/repos/hg
    ]]]
    
    @options

    == valid URLs:

    Valid URLs are of the form:

      local/filesystem/path (or file://local/filesystem/path)
      http://[user[:pass]@]host[:port]/[path]
      https://[user[:pass]@]host[:port]/[path]
      ssh://[user[:pass]@]host[:port]/[path]

    Paths in the local filesystem can either point to Mercurial
    repositories or to bundle files (as created by 'hg bundle' or
    'hg incoming --bundle').

    An optional identifier after # indicates a particular branch, tag,
    or changeset to pull.

    [[[
    == using SSH with Mercurial:
        
    - SSH requires an accessible shell account on the destination machine
      and a copy of hg in the remote path or specified with as remotecmd.
    - path is relative to the remote user's home directory by default.
      Use an extra slash at the start of a path to specify an absolute path:
        ssh://example.com//tmp/repository
    - Mercurial doesn't use its own compression via SSH; the right thing
      to do is to configure it in your ~/.ssh/config, e.g.:
        Host *.mylocalnetwork.example.com
          Compression no
        Host *
          Compression yes
      Alternatively specify "ssh -C" as your ssh command in your hgrc or
      with the --ssh command line option.
    ]]]
    """

And here is its verbose output:

hg pull [-u] [-f] [-r REV]... [-e CMD] [--remotecmd CMD] [SOURCE]

pull changes from the specified source

    Pull changes from a remote repository to a local one.

    This finds all changes from the repository at the specified path
    or URL and adds them to the local repository. By default, this
    does not update the copy of the project in the working directory.
    Examples:
    
      hg pull my/other/repo
      hg pull -u http://selenic.com/repos/hg

options:

 -u --update     update to new tip if changesets were pulled
 -f --force      run even when remote repository is unrelated
 -r --rev        a specific revision up to which you would like to pull
 -e --ssh        specify ssh command to use
    --remotecmd  specify hg command to run on the remote side
    --rebase     rebase working directory to branch head

valid URLs:

    Valid URLs are of the form:

      local/filesystem/path (or file://local/filesystem/path)
      http://[user[:pass]@]host[:port]/[path]
      https://[user[:pass]@]host[:port]/[path]
      ssh://[user[:pass]@]host[:port]/[path]

    Paths in the local filesystem can either point to Mercurial
    repositories or to bundle files (as created by 'hg bundle' or
    'hg incoming --bundle').

    An optional identifier after # indicates a particular branch, tag,
    or changeset to pull.

using SSH with Mercurial:
        
    - SSH requires an accessible shell account on the destination machine
      and a copy of hg in the remote path or specified with as remotecmd.
    - path is relative to the remote user's home directory by default.
      Use an extra slash at the start of a path to specify an absolute path:
        ssh://example.com//tmp/repository
    - Mercurial doesn't use its own compression via SSH; the right thing
      to do is to configure it in your ~/.ssh/config, e.g.:
        Host *.mylocalnetwork.example.com
          Compression no
        Host *
          Compression yes
      Alternatively specify "ssh -C" as your ssh command in your hgrc or
      with the --ssh command line option.

CategoryNewFeatures