Ignore:
Timestamp:
24 Feb 2014, 06:43:26 (11 years ago)
Author:
Henrik Bettermann
Message:

Update INSTALL.txt and integrate into Sphinx documentation. Remove redundancies.

File:
1 edited

Legend:

Unmodified
Added
Removed

  • main/waeup.kofa/trunk/docs/source/developerdocs/developernotes.rst

    r7818 r11386  
    1010===========================
    1111
    12 The installation is described for Linux-based computers.
    13 
    14 Preparing the system
    15 --------------------
    16 
    17 To create a working copy of the WAeUP.Kofa we recommend use of
    18 `virtualenv`. You, however, need also some basic libraries, a C
    19 compiler and some things more.
    20 
    21 What you need (Debian/Ubuntu package names in brackets):
    22 
    23 * Python 2.6 (python2.6)
    24 
    25   Currently, also Python2.5 is supported but we want to make use of
    26   some of the 2.6 goodies in the future.
    27 
    28 
    29 * Python 2.6 development files (python2.6-dev)
    30 
    31 * A C-Compiler (gcc)
    32 
    33 * The C library development files (libc6-dev)
    34 
    35 * A subversion client (svn)
    36 
    37 * enscript (enscript) [optional]
    38 
    39   This is only needed if you want test coverage reports.
    40 
    41 All these packages can be installed on Debian systems like this::
    42 
    43   # apt-get install python2.6 python2.6-dev python2.6-dbg \
    44                     gcc libc6-dev svn enscript
    45 
    46 Afterwards you should be able to enter::
    47 
    48   $ python2.6
    49 
    50 at the commandline and get a Python prompt. Quit the interpreter
    51 pressing <CTRL-D>.
    52 
    53 Installing `virtualenv`
    54 -----------------------
    55 
    56 We recommend use of `virtualenv` to create Python sandboxes where you
    57 can run your code without touching any other installations.
    58 
    59 If you don't already have ``easy_install`` available, you can find the
    60 script to set it up on the `PEAK EasyInstall page`_.
    61 
    62 .. _`PEAK EasyInstall page`: http://peak.telecommunity.com/DevCenter/EasyInstall#installing-easy-install
    63 
    64 You need to download `ez_setup.py`_. Then, you run it like this to
    65 install ``easy_install`` into your system Python::
    66 
    67   $ sudo python2.6 ez_setup.py
    68 
    69 .. _`ez_setup.py`: http://peak.telecommunity.com/dist/ez_setup.py
    70 
    71 This will make ``easy_install`` available to you.
    72 
    73 .. note:: Sometimes you have ``easy_install`` installed but you need a
    74           newer version of the underlying setuptools infrastructure to
    75           make Grok work. You can upgrade setuptools with::
    76 
    77             $ sudo easy_install -U setuptools
    78 
    79 Now you can install `virtualenv` by doing (as root)::
    80 
    81   # easy_install-2.6 virtualenv
    82 
    83 This step will fetch all needed sources from the internet and install
    84 `virtualenv` locally in your Python2.6 installation.
    85 
    86 
    87 Creating a sandbox
    88 ------------------
    89 
    90 This step is only necessary (and recommended) if you installed
    91 `virtualenv` before.
    92 
    93 As a normal user you now can create a sandbox for your upcoming work
    94 by::
    95 
    96   $ virtualenv --no-site-packages mysandbox
    97 
    98 where ``mysandbox`` is a directory in the filesystem where your
    99 sandbox will be created. `virtualenv` will also create this directory
    100 for you.
    101 
    102 By passing the ``no-site-packages`` switch we tell `virtualenv` to
    103 provide us a clean environment without any extra-packages installed
    104 systemwide.
    105 
    106 If you have a look into the freshly created sandbox, you will notice
    107 that in the ``bin/`` directory there is also
    108 
    109 You now can activate the sandbox by doing::
    110 
    111   $ source mysandbox/bin/activate
    112 
    113 You will notice that the input prompt changes.
    114 
    115 To deactivate the sandbox at any time, enter::
    116 
    117   $ deactivate
    118 
    119 and the prompt will be the same as before the activation.
    120 
    121 For the following steps make sure the sandbox is active.
    122 
    123 
    124 Creating a working place
    125 ------------------------
    126 
    127 In the sandbox (or anywhere else) we now create our real working
    128 environment. To do this, we change to the sandbox and checkout the
    129 sources of the WAeUP.Kofa from the subversion server::
    130 
    131   $ cd mysandbox/
    132   $ svn co https://svn.waeup.org/repos/main/waeup.kofa/trunk waeup-trunk
    133 
    134 where ``waeup-trunk`` is only a name we've chosen here to make clear
    135 where the sources come from.
    136 
    137 This command should fetch the sources of the WAeUP sources for you and
    138 put it in the directory ``waeup-trunk/``.
    139 
    140 Now enter the new directory::
    141 
    142   $ cd waeup-trunk
    143 
    144 
    145 Preparing the build
    146 -------------------
    147 
    148 In the sources directory (``waeup-trunk/``) you have to prepare the
    149 project to fetch needed components (eggs), compile C-code parts,
    150 etc. This steip will not touch any external projects::
    151 
    152   $ python2.6 bootstrap.py
    153 
    154 This will generate some directories and the ``buildout`` script in
    155 ``bin/`` for us. This step must be executed only once for each
    156 instance.
    157 
    158 Now we can do the real build by triggering::
    159 
    160   $ bin/buildout
    161 
    162 If this is your first install of some Grok-related project, this step
    163 will need some time as lots of sources have to be fetched, many
    164 components must be compiled, etc.
    165 
    166 This step must be redone whenever you change something in
    167 ``buildout.cfg`` or ``setup.py``.
    168 
    169 Afterwards we are ready to go.
    170 
    171 
    172 Start the instance
    173 ------------------
    174 
    175 You should be able now to start the created instance by doing::
    176 
    177    $ bin/zopectl fg
    178 
    179 If you now point a browser to::
    180 
    181    localhost:8080
    182 
    183 you should get a login pop-up, where you can login as superuser with
    184 ``grok`` and ``grok`` as username/password.
    185 
    186 If you want to change the default credentials, have a look into
    187 ``buildout.cfg`` where the superuser password is determined.
    188 
    189 You can stop the instance by pressing <CTRL-C>.
    190 
    191 
     12See :ref:`installing_linux`
    19213
    19314Documentation
    … …  
    20021become both: executable (i.e. testable) examples and documentation.
    20122
    202 Generating documentation
    203 ------------------------
     23Building documentation
     24----------------------
    20425
    205 We use the excellent `Sphinx <http://sphinx.pocoo.org/>`_ Python
    206 documentation generator to generate the docs as HTML pages.
    207 
    208 The documentation of the :mod:`waeup.kofa` project can easily be
    209 created doing::
    210 
    211   $ bin/waeupdocs
    212 
    213 This will create a tree of HTML pages in
    214 ``parts/waeupdocs/waeup.kofa/build/waeup.kofa/`` which you can for
    215 instance browse by pointing your browser to this location.
    216 
    217 An 'official' place in internet for the whole docs is about to come
    218 but not yet available.
    219 
     26See :ref:`building_documentation`
    22027
    22128Writing documentation
    … …  
    22532at the same time. See the many .txt files in the :mod:`waeup.kofa`
    22633package for examples.
    227 
    22834
    22935Testing
Note: See TracChangeset for help on using the changeset viewer.