1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/README.txt Thu Feb 17 01:09:56 2011 +0100
1.3 @@ -0,0 +1,147 @@
1.4 +Introduction
1.5 +------------
1.6 +
1.7 +The moinsetup script is a utility separate from MoinMoin which attempts to
1.8 +assist in the configuration and deployment of MoinMoin and extensions. It can
1.9 +automate the installation of MoinMoin according to recommended practices,
1.10 +create and initialise new Wiki instances, install extensions, themes and
1.11 +related resources, and perform certain configuration changes.
1.12 +
1.13 +Usage
1.14 +-----
1.15 +
1.16 +Running moinsetup as follows will provide a list of methods available:
1.17 +
1.18 + python moinsetup.py
1.19 +
1.20 +Before any work can be done by the program, a configuration file needs to be
1.21 +created. See the supplied moinsetup.cfg file for an example file which can
1.22 +be modified and used for this purpose.
1.23 +
1.24 +Configuration
1.25 +-------------
1.26 +
1.27 +The configuration file has two sections: installation and site. A brief
1.28 +description of the settings is given below.
1.29 +
1.30 +Installation settings influence the configuration, installation and
1.31 +customisation of a Wiki and are generally not optional:
1.32 +
1.33 +moin_distribution A path to a MoinMoin distribution directory, which can
1.34 + also be a clone of a MoinMoin repository.
1.35 +
1.36 +prefix The directory prefix containing lib, bin and share
1.37 + directories where MoinMoin is (or will be) installed.
1.38 + Although this follows the layout of the /usr directory (on
1.39 + Unix-based systems), it is likely that MoinMoin may be
1.40 + installed elsewhere
1.41 +
1.42 +web_app_dir A directory where the moin.cgi program is (or will be)
1.43 + installed.
1.44 +
1.45 +web_site_dir The directory where sites available to the Apache Web
1.46 + server are defined. This directory may just be a place
1.47 + where initial site definitions are written, and after
1.48 + manual editing, such definitions may be copied to the
1.49 + appropriate location.
1.50 +
1.51 +common_dir The directory in which the Wiki instance being configured
1.52 + or managed resides (or will reside).
1.53 +
1.54 +Site settings are generally only relevant when configuring and installing a
1.55 +Wiki:
1.56 +
1.57 +url_path The URL path (after the host details) of the Wiki.
1.58 +superuser The superuser of the Wiki.
1.59 +site_name The name of the Wiki.
1.60 +front_page_name The name of the Wiki's front page.
1.61 +theme_default The default theme of the Wiki.
1.62 +
1.63 +Examples
1.64 +--------
1.65 +
1.66 +Some of the more useful invocation methods are described below using examples.
1.67 +
1.68 +To set up MoinMoin and a Wiki instance:
1.69 +
1.70 + python moinsetup.py setup
1.71 +
1.72 +To only set up a Wiki instance using a different configuration file:
1.73 +
1.74 + python moinsetup.py -f new_wiki.cfg setup_wiki
1.75 +
1.76 +To change a configuration setting (for example, the default theme):
1.77 +
1.78 + python moinsetup.py reconfigure_moin theme_default mercurialwiki
1.79 +
1.80 +To install a theme from a directory containing a theme module, css and img
1.81 +directories (for example, MercurialWikiTheme):
1.82 +
1.83 + python moinsetup.py install_theme /path/to/MercurialWikiTheme/themes/mercurialwiki
1.84 +
1.85 +To install an extension package from a directory containing a setup.py script
1.86 +(for example, EventAggregator):
1.87 +
1.88 + python moinsetup.py install_extension_package /path/to/EventAggregator
1.89 +
1.90 +To install actions from a directory containing action modules:
1.91 +
1.92 + python moinsetup.py install_actions /path/to/EventAggregator/actions
1.93 +
1.94 +To install macros from a directory containing macro modules:
1.95 +
1.96 + python moinsetup.py install_macros /path/to/EventAggregator/macros
1.97 +
1.98 +To install theme-related resources for an extension from a directory
1.99 +containing css and img directories:
1.100 +
1.101 + python moinsetup.py install_theme_resources /path/to/EventAggregator
1.102 +
1.103 +To add theme-related resources to existing stylesheets (for example, adding
1.104 +the event-aggregator.css resource to the screen.css stylesheet for all
1.105 +installed themes):
1.106 +
1.107 + python moinsetup.py edit_theme_stylesheet screen.css event-aggregator.css
1.108 +
1.109 +To make a page package containing pages to be added to a Wiki:
1.110 +
1.111 + python moinsetup.py make_page_package pages_dir pages.zip
1.112 +
1.113 +To install a page package in a Wiki:
1.114 +
1.115 + python moinsetup.py install_page_package pages.zip
1.116 +
1.117 +Contact, Copyright and Licence Information
1.118 +------------------------------------------
1.119 +
1.120 +See the following Web page for more information about this work:
1.121 +
1.122 +http://moinmo.in/ScriptMarket/moinsetup
1.123 +
1.124 +The author can be contacted at the following e-mail address:
1.125 +
1.126 +paul@boddie.org.uk
1.127 +
1.128 +Copyright and licence information can be found in the docs directory - see
1.129 +docs/COPYING.txt and docs/LICENCE.txt for more information.
1.130 +
1.131 +Dependencies
1.132 +------------
1.133 +
1.134 +moinsetup has the following basic dependencies:
1.135 +
1.136 +Packages Release Information
1.137 +-------- -------------------
1.138 +
1.139 +CMDsyntax Tested with 0.91
1.140 + Source: http://www.boddie.org.uk/david/Projects/Python/CMDSyntax/index.html
1.141 +
1.142 +Release Procedures
1.143 +------------------
1.144 +
1.145 +Update the moinsetup.py __version__ attribute.
1.146 +Change the version number and package filename/directory in the documentation.
1.147 +Update the release notes (see above).
1.148 +Tag, export.
1.149 +Archive, upload.
1.150 +Update the ScriptMarket (see above for the URL).