Changeset 299:a67ef543f067

Show
Ignore:
Timestamp:
2007-08-31 20:59:24 (1 year ago)
Author:
Stefan Schwarzer <sschwarzer@sschwarzer.net>
branch:
default
Message:
Added documentation in man page style.
Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • config.py

    r297 r299  
    2424""" 
    2525Configure the application. 
     26""" 
     27 
     28import sys 
     29 
     30 
     31MAN_PAGE = """\ 
     32NAME 
     33 
     34  Websourcebrowser - conveniently browse source code with a webbrowser 
     35 
     36SYNOPSIS 
     37 
     38  wsbrowser [options] 
     39 
     40  The name of the executable is wsbrowser on Posix and wsbrowser.py on 
     41  Windows. 
     42 
     43DESCRIPTION 
     44 
     45  Websourcebrowser starts an internal webserver and listens for HTTP 
     46  requests for directories and files in a project's source code 
     47  directory. The web interface allows to browse the source code with a 
     48  left frame containing the directory tree and a right frame a 
     49  selected file. The directory frame is always accessible. 
     50 
     51  If Pygments (http://pygments.org) is installed, files may be 
     52  displayed with syntax highlighting. 
     53 
     54OPTIONS 
     55 
     56  -h, --help 
     57        Show this help text and exit. 
     58 
     59  -r ROOT, --root=ROOT 
     60        Set the document root directory (default: current directory). 
     61        For example, if --root=/my/greatproject is specified, the URL 
     62        path / will correspond to the directory /my/greatproject. 
     63        Directories or files "above" the root directory aren't 
     64        accessible (probably, see section BUGS). 
     65 
     66  -t PROJECT_TITLE, --project-title=PROJECT_TITLE 
     67        Set the project title to display as the title of the frameset 
     68        (default: capitalized base name of the root directory, so the 
     69        above root option sets a project title "Greatproject"). 
     70 
     71  --project-homepage=PROJECT_HOMEPAGE 
     72        Make the specified URL accessible via the "Homepage" link in 
     73        the left frame (default: the Websourcebrowser homepage). 
     74 
     75  -d DIR_LEVELS, --dir-levels=DIR_LEVELS 
     76        Set the directory nesting level for the tree display in the 
     77        left frame (default: 1). The number 1 denotes a linear list, 2 
     78        additionally shows the direct subdirectories etc. 
     79 
     80        Using a large number will display the directory tree 
     81        completely expanded but may make the browsing rather slow for 
     82        a large directory tree. Thus it's recommended to keep the 
     83        default, 1. 
     84 
     85  --dir-indent=DIR_INDENT 
     86        Set the number of characters for indentation per directory 
     87        level (default: 4). 
     88 
     89  -i PATTERN, --ignore-pattern=PATTERN 
     90        Ignore directories and files matching this pattern (default: 
     91        nothing is ignored). To specify more than one pattern, repeat 
     92        this option. 
     93 
     94        Example: To ignore all Subversion bookkeeping files, use 
     95        --ignore-pattern="/*.svn" --ignore-pattern="/*.svn/*" 
     96 
     97  -l, --line-numbers 
     98        Prepend lines of text files with line numbers (default: no 
     99        line numbers). 
     100 
     101        This works only if Pygments is installed, otherwise this 
     102        option is ignored. 
     103 
     104  --http-host=HTTP_HOST 
     105        Use the specified host name or IP for the local interface to 
     106        listen on (default: localhost). 
     107 
     108        With the defaults for --http-host and --http-port, the address 
     109        line in the browser is http://localhost:8000/ . 
     110 
     111  --http-port=HTTP_PORT 
     112        Listen on this HTTP port (default: 8000). 
     113 
     114        With the defaults for --http-host and --http-port, the address 
     115        line in the browser is http://localhost:8000/ . 
     116 
     117  -c CLIENT, --allowed-client=CLIENT 
     118        Allow remote access from this host name or IP address 
     119        (default: allow only access from localhost). The localhost 
     120        address is always included. For multiple host names or IP 
     121        addresses use the option several times. For example: 
     122 
     123        wsbrowser -c my.host.com -c 199.243.19.27 
     124 
     125        As a special case, specifying ALL as the options value accepts 
     126        requests from all addresses and so effectively makes 
     127        Websourcebrowser a web server on the public internet, unless 
     128        prevented by a router or firewall. 
     129 
     130  --logging 
     131        Activate logging of HTTP accesses to standard output (default: 
     132        no logging). 
     133 
     134ENVIRONMENT 
     135 
     136  WSB_IGNORE 
     137        Set wildcard patterns to ignore. If multiple patterns are 
     138        given, they must be separated with commas. Note that 
     139        whitespace is significant and is treated as part of the 
     140        respective pattern. 
     141 
     142        A typical example for WSB_IGNORE might be 
     143        *.pyc,*.pyo,*/.svn,*.svn/*,*/.hg,*/.hg/*,*.swp 
     144        (without the leading and trailing whitespace; note also that 
     145        there's no whitespace before or after the commas). 
     146 
     147        If both this environment variable and one or more 
     148        --ignore-pattern options are used, the patterns from the 
     149        command line are added to those from the environment variable. 
     150 
     151BUGS 
     152 
     153  Probably there are some bugs as Websourcebrowser is still alpha 
     154  software. Currently, I don't recommend to use Websourcebrowser for 
     155  use on the public internet because it may contain significant 
     156  vulnerabilities. (I indeed paid attention to security though I would 
     157  welcome an experienced fellow to spot security problems.) 
     158 
     159  Since the software is still in the alpha stage, it may still change 
     160  significantly. This may include incompatible variations like 
     161  removing command line options or changing their semantics. 
     162 
     163AUTHOR 
     164 
     165  The author of Websourcebrowser is 
     166  Stefan Schwarzer <sschwarzer@sschwarzer.net>. 
     167 
     168SEE ALSO 
     169 
     170  The pydoc module in the Python distribution similarly acts as a 
     171  webserver if it's invoked as a program with the option -p and a port 
     172  number. 
    26173""" 
    27174 
    …… 
    119266        args = sys.argv[1:] 
    120267    # set up command line parser 
    121     parser = optparse.OptionParser() 
     268    parser = optparse.OptionParser(add_help_option=False) 
     269    parser.add_option("-h", "--help", action='store_true') 
    122270    parser.add_option("-r", "--root", help="document root [current directory]") 
    123271    parser.add_option("-t", "--project-title", 
    …… 
    139287                      help="prepend text lines with line numbers [no]") 
    140288    parser.add_option("--http-host", help="local HTTP interface [localhost]") 
    141     parser.add_option("-p", "--http-port", "--port", type='int', 
     289    parser.add_option("--http-port", type='int', 
    142290                      help="HTTP port to listen on [%default]") 
    143291    parser.add_option("-c", "--allowed-client", metavar="CLIENT", 
    …… 
    149297    parser.set_defaults(**globals()) 
    150298    (options, args) = parser.parse_args(args) 
     299    if options.help: 
     300        print MAN_PAGE 
     301        sys.exit() 
    151302    # from here on, `args` is the list of only the positional arguments! 
    152303    if args: