Annotated README.txt

2011-09-14 Paul Boddie Introduced a special site-packages location setting where libraries are installed outside the prefix hierarchy. Added more specific error messages when unsuitable or insufficient settings are given. Added an example configuration file for Debian-compatible systems.
paul@27 1
paul@27 2
paul@27 3
paul@27 4
The moinsetup script is a utility separate from MoinMoin which attempts to
paul@27 5
assist in the configuration and deployment of MoinMoin and extensions. It can
paul@27 6
automate the installation of MoinMoin according to recommended practices,
paul@27 7
create and initialise new Wiki instances, install extensions, themes and
paul@27 8
related resources, and perform certain configuration changes.
paul@27 9
paul@27 10
paul@27 11
paul@27 12
paul@27 13
Running moinsetup as follows will provide a list of methods available:
paul@27 14
paul@27 15
paul@27 16
paul@27 17
Before any work can be done by the program, a configuration file needs to be
paul@27 18
created. See the supplied moinsetup.cfg file for an example file which can
paul@27 19
be modified and used for this purpose.
paul@27 20
paul@27 21
paul@27 22
paul@27 23
paul@36 24
The configuration file has two sections: "installation" and "site". A brief
paul@27 25
description of the settings is given below.
paul@27 26
paul@27 27
Installation settings influence the configuration, installation and
paul@27 28
customisation of a Wiki and are generally not optional:
paul@27 29
paul@27 30
moin_distribution   A path to a MoinMoin distribution directory, which can
paul@27 31
                    also be a clone of a MoinMoin repository.
paul@27 32
paul@40 33
moin_data           A path to the MoinMoin shared data, which may be installed
paul@40 34
                    from a system package in a directory such as
paul@40 35
paul@40 36
paul@27 37
prefix              The directory prefix containing lib, bin and share
paul@27 38
                    directories where MoinMoin is (or will be) installed.
paul@27 39
                    Although this follows the layout of the /usr directory (on
paul@27 40
                    Unix-based systems), it is likely that MoinMoin may be
paul@27 41
                    installed elsewhere
paul@27 42
paul@27 43
web_app_dir         A directory where the moin.cgi program is (or will be)
paul@27 44
paul@27 45
paul@36 46
web_static_dir      A directory from which static resources are to be served.
paul@36 47
                    This directory need only be specified in a limited hosting
paul@36 48
                    environment (see below for more details).
paul@36 49
paul@27 50
web_site_dir        The directory where sites available to the Apache Web
paul@27 51
                    server are defined. This directory may just be a place
paul@27 52
                    where initial site definitions are written, and after
paul@27 53
                    manual editing, such definitions may be copied to the
paul@36 54
                    appropriate location. If this directory is left
paul@36 55
                    unspecified, a limited hosting environment will be
paul@36 56
paul@36 57
paul@36 58
Except for the common_dir setting, site settings are generally only relevant
paul@36 59
when configuring and installing a Wiki:
paul@27 60
paul@27 61
common_dir          The directory in which the Wiki instance being configured
paul@27 62
                    or managed resides (or will reside).
paul@27 63
paul@27 64
url_path            The URL path (after the host details) of the Wiki.
paul@27 65
superuser           The superuser of the Wiki.
paul@27 66
site_name           The name of the Wiki.
paul@27 67
front_page_name     The name of the Wiki's front page.
paul@27 68
theme_default       The default theme of the Wiki.
paul@27 69
paul@36 70
Limited Hosting Environments
paul@36 71
paul@36 72
paul@36 73
Sometimes, the hosting environment in which MoinMoin is to be deployed will be
paul@36 74
restrictive or "limited", meaning that substantial configuration of the Web
paul@36 75
server will not be possible for the user installing and configuring MoinMoin.
paul@36 76
In such environments, users will typically be allowed to install content in
paul@36 77
preconfigured directories for static and dynamic content. For example:
paul@36 78
paul@36 79
/path/to/www/cgi-bin    a dynamic content directory, providing CGI scripts
paul@36 80
/path/to/www/htdocs     a static content directory, providing Web pages
paul@36 81
paul@36 82
To work in such environments, specify the configuration settings in
paul@36 83
moinsetup.cfg as follows:
paul@36 84
paul@36 85
web_app_dir     = /path/to/www/cgi-bin
paul@36 86
web_static_dir  = /path/to/www/htdocs
paul@36 87
web_site_dir    =
paul@36 88
paul@36 89
Inside the static resources directory, a subdirectory will be created to hold
paul@36 90
any static content used by MoinMoin.
paul@36 91
paul@27 92
paul@27 93
paul@27 94
paul@27 95
Some of the more useful invocation methods are described below using examples.
paul@27 96
paul@27 97
To set up MoinMoin and a Wiki instance:
paul@27 98
paul@27 99
  python setup
paul@27 100
paul@27 101
To only set up a Wiki instance using a different configuration file:
paul@27 102
paul@27 103
  python -f new_wiki.cfg setup_wiki
paul@27 104
paul@36 105
To change a Wiki configuration setting (for example, the default theme):
paul@27 106
paul@27 107
  python reconfigure_moin theme_default mercurialwiki
paul@27 108
paul@27 109
To install a theme from a directory containing a theme module, css and img
paul@27 110
directories (for example, MercurialWikiTheme):
paul@27 111
paul@27 112
  python install_theme /path/to/MercurialWikiTheme/themes/mercurialwiki
paul@27 113
paul@27 114
To install an extension package from a directory containing a script
paul@27 115
(for example, EventAggregator):
paul@27 116
paul@27 117
  python install_extension_package /path/to/EventAggregator
paul@27 118
paul@27 119
To install actions from a directory containing action modules:
paul@27 120
paul@27 121
  python install_actions /path/to/EventAggregator/actions
paul@27 122
paul@27 123
To install macros from a directory containing macro modules:
paul@27 124
paul@27 125
  python install_macros /path/to/EventAggregator/macros
paul@27 126
paul@27 127
To install theme-related resources for an extension from a directory
paul@27 128
containing css and img directories:
paul@27 129
paul@27 130
  python install_theme_resources /path/to/EventAggregator
paul@27 131
paul@27 132
To add theme-related resources to existing stylesheets (for example, adding
paul@27 133
the event-aggregator.css resource to the screen.css stylesheet for all
paul@27 134
installed themes):
paul@27 135
paul@27 136
  python edit_theme_stylesheet screen.css event-aggregator.css
paul@27 137
paul@27 138
To make a page package containing pages to be added to a Wiki:
paul@27 139
paul@27 140
  python make_page_package pages_dir
paul@27 141
paul@27 142
To install a page package in a Wiki:
paul@27 143
paul@27 144
  python install_page_package
paul@27 145
paul@27 146
Contact, Copyright and Licence Information
paul@27 147
paul@27 148
paul@27 149
See the following Web page for more information about this work:
paul@27 150
paul@27 151
paul@27 152
paul@27 153
The author can be contacted at the following e-mail address:
paul@27 154
paul@27 155
paul@27 156
paul@27 157
Copyright and licence information can be found in the docs directory - see
paul@29 158
docs/COPYING.txt and docs/gpl-3.0.txt for more information.
paul@27 159
paul@27 160
paul@27 161
paul@27 162
paul@27 163
moinsetup has the following basic dependencies:
paul@27 164
paul@27 165
Packages                    Release Information
paul@27 166
--------                    -------------------
paul@27 167
paul@27 168
CMDsyntax                   Tested with 0.91
paul@27 169
paul@27 170
paul@40 171
New in moinsetup 0.3 (Changes since moinsetup 0.2)
paul@40 172
paul@40 173
paul@40 174
  * Added a moin_data setting and made moin_distribution optional so that when
paul@40 175
    MoinMoin is installed from a system package, the non-installation actions
paul@40 176
    can still be performed.
paul@40 177
paul@35 178
New in moinsetup 0.2 (Changes since moinsetup 0.1)
paul@35 179
paul@35 180
paul@35 181
  * Improved OpenID configuration, supporting MoinMoin 1.9, and added support
paul@35 182
    for other authentication methods.
paul@35 183
  * Added support for ACL-capable filesystems when setting Wiki permissions.
paul@35 184
    It can be more convenient to retain read/write access to the installed
paul@35 185
    files while also granting the Web server user (who need not be in a common
paul@35 186
    group) access to read and modify the files.
paul@35 187
  * Added support for configurations employing a separate static resources
paul@35 188
    directory (such as a typical "htdocs" directory).
paul@35 189
  * Added a parser installation action.
paul@35 190
  * Added support for page attachments in the page-packaging action.
paul@35 191
paul@27 192
Release Procedures
paul@27 193
paul@27 194
paul@27 195
Update the __version__ attribute.
paul@27 196
Change the version number and package filename/directory in the documentation.
paul@27 197
Update the release notes (see above).
paul@27 198
Tag, export.
paul@27 199
Archive, upload.
paul@27 200
Update the ScriptMarket (see above for the URL).