.. Matholymp documentation introduction. Copyright 2014-2020 Joseph Samuel Myers. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program. If not, see . Additional permission under GNU GPL version 3 section 7: If you modify this program, or any covered work, by linking or combining it with the OpenSSL project's OpenSSL library (or a modified version of that library), containing parts covered by the terms of the OpenSSL or SSLeay licenses, the licensors of this program grant you additional permission to convey the resulting work. Corresponding Source for a non-source form of such a combination shall include the source code for the parts of OpenSSL used as well as that of the covered work. Introduction, prerequisites and downloads ========================================= Matholymp is software for creating and maintaining websites for mathematical olympiads, with online registration and support for various associated administrative functions. Matholymp is free software, written in `Python `_ and available under the `GNU General Public License, version 3 `_. Matholymp is written and maintained by `Joseph Myers `_. It was originally developed for the `European Girls' Mathematical Olympiad `_. The following events are known to use matholymp; please let me know if you're using it for your event and I'll add it to the list. * `European Girls' Mathematical Olympiad `_. The following prerequisite software should be installed to use matholymp: * `Python `_, version 3.5 or later. * `PyICU `_ (which in turn requires `ICU `_). * `Roundup `_ (used to provide a web interface for editing databases for the online registration system; the issue-tracking parts of Roundup, and the email interface, are not used; Roundup is not needed if the online registration system is not used). Use of the current version of Roundup, 2.0.0 as of this writing, is recommended; older versions will not work because of Roundup API changes. Some bugs relevant to some uses of matholymp are still present in 2.0.0, so you should consider applying the patches in the :file:`roundup-patches/` directory in the matholymp source distribution before installing Roundup. See :ref:`roundup-patches` for more details of those patches. * `PyPDF2 `_ (used in generating PDF documents from registration system data, and also required in the registration system whether document generation is used or not; not needed if those parts of matholymp are not used). * `Pillow `_, built with support for JPEG and PNG files. * `LaTeX `_; specifically, the :command:`pdflatex` command (used in generating PDF documents from registration system data; not needed if that part of matholymp is not used). * A web server such as Apache, and a database server (MySQL or PostgreSQL), are also recommended for use with the online registration system. (For testing purposes, you can use Roundup's built-in web server and its support for Python's :py:mod:`dbm`.) * To generate the formatted documentation, `Sphinx `_ is needed. This is not needed simply to use matholymp. If you are reading this document online, note that it relates to version |release|; if you are using a different matholymp version (including if you are using the current development sources), you may wish to format the documentation for that version using Sphinx, which can be done with the provided :command:`mo-sphinx-build` script, or read the documentation sources in the :file:`docs/` directory of the source distribution directly. (Run :command:`mo-sphinx-build` with an empty working directory; it generates its output in the current directory.) * To run automated tests of the registration system, `MechanicalSoup `_ (which in turn has some other dependencies) is needed. Those tests are only expected to work on Unix-like operating systems. * To measure the code coverage of the automated tests, `Coverage.py `_ is needed. This is only relevant for developing matholymp, not for using it. The ``--coverage`` option to :command:`mo-run-tests` is used for measuring coverage. The matholymp code is intended to be independent of the operating system used. However, it has only been tested on GNU/Linux (specifically, various versions of Ubuntu) and so it is likely you will need to debug portability issues if not using it on a Unix-like operating system. (Other Unix-like operating systems are unlikely to be a problem. They may vary in the extent to which the prerequisites listed above are available prepackaged or have to be locally built. I have no recommendations regarding whether you should use packaged versions where available or build these prerequisites locally; that is a matter of personal preference.) Releases of matholymp are available for download: * 2020.07.0 (`sources `_, `GPG signature `_). * 2018.02.0 (`sources `_, `GPG signature `_). * 2017.05.0 (`sources `_, `GPG signature `_). * 2017.01.0 (`sources `_, `GPG signature `_). * 2016.05.0 (`sources `_, `GPG signature `_). * 2016.01.0 (`sources `_, `GPG signature `_). * 2015.04.0 (`sources `_, `GPG signature `_). * 2015.01.0 (`sources `_, `GPG signature `_). * 2014.09.0 (`sources `_, `GPG signature `_). The current development sources of matholymp are available using `Git `_:: git clone https://git.ukmt.org.uk/matholymp-py.git or:: git clone git://git.ukmt.org.uk/git/matholymp-py.git There is also a `mirror on GitHub `_. The matholymp code can be used directly from its source directory; no installation is required. If you run the provided scripts from the source directory, they will automatically find the Python modules in the :file:`matholymp/` directory. However, you will need to ensure these modules can be found when the Roundup registration system is run (for example, by creating a symbolic link from the :file:`site-packages/` directory where Roundup was installed to the :file:`matholymp/` directory, or by setting :envvar:`PYTHONPATH` appropriately). Some parts of the matholymp code have a testsuite, which can be run with :command:`mo-run-tests`; all tests should pass. The matholymp functionality falls into three main areas. Although the software is designed as an integrated whole, you can also choose to use only parts of the functionality. Whichever parts of the system you use, you will be maintaining directories containing configuration files and other content such as photos on the static site and LaTeX and HTML templates. It is a good idea to maintain these directories in a version control system such as Git in case any problems arise and you need to undo a change made. You will also need to ensure that all these directories are included in your system's backup arrangements, and ensure that databases for the registration system are backed up as well (which typically means the backup process running database dumps to ensure the backup contains a consistent state, rather than backing up the raw files containing the database). * :ref:`static-site`. * :ref:`online-registration`. * :ref:`document-generation`.