Merge branch 'master' of https://github.molgen.mpg.de/EditionOpenAcce…

…ss/eoa-1.5

docs/conf.py

@@ -20,8 +20,8 @@
 # -- Project information -----------------------------------------------------
 
 project = 'EOA Publication Platform'
-copyright = '2020, Klaus Thoden'
-author = 'Klaus Thoden'
+copyright = '2020, Max Planck Institute for the History of Science'
+author = 'Samuel Gfrörer and Klaus Thoden'
 
 # The full version, including alpha/beta/rc tags
 release = '1.5'
@@ -70,5 +70,9 @@
 
 # -- Options for intersphinx extension ---------------------------------------
 
+DOC_URL = "http://localhost:7999"
+
 # Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {'https://docs.python.org/3/': None}
+intersphinx_mapping = {'main': (f'{DOC_URL}/', None)
+                       'webplat': (f'{DOC_URL}/webdesign_platform', None),
+}

docs/install_docker.rst

@@ -1,3 +1,147 @@
 ==========================
  Installation with Docker
 ==========================
+
+Docker is used to provide a consistent environment. Additional Python scripts are used for automisation of the installation process. This solution also contains the EOASkripts suite, which effectively makes this an all-in-one-solution for the whole production infrastructure.
+
+Dependencies to other git repositories are handled using `git_deps_py <https://github.molgen.mpg.de/EditionOpenAccess/git_deps_py>`_.
+
+Configuration
+=============
+- Environment variables: see file ``.env``
+
+	These variables are available inside the ``docker-compose.yaml`` file and are also loaded into the Python scripts.
+	(The ``.env`` file is initially created with default settings by the ``init.py`` script)
+
+- Django settings: see ``src/eoa/settings.py``
+
+	For further information please check the Django documentation.
+
+Prerequisites
+=============
+
+- Python 3
+- Docker, Docker Compose
+- `git_deps_py <https://github.molgen.mpg.de/EditionOpenAccess/git_deps_py>`_
+
+Initialise the Repository
+=========================
+Initialise the repository with the following commands::
+
+	$ git_deps_py
+	$ ./scripts/init.py --build
+
+This will pull remote repositories and resources, initialize the database, etc.
+The ``--build`` parameter forces the recreation of the docker image, e.g. if ``Dockerfile`` or ``requirements.txt`` have changed.
+
+Import data
+===========
+
+Initialize CMS pages
+--------------------
+The dummy fixture contains the default setup for CMS pages.
+Also a CMS superuser with username ``test`` and password ``test`` (don't use this in production !)::
+
+	$ cp fixtures/cms_dummy.json res/fixtures/
+	$ ./scripts/init.py --skip-db
+	$ ./scripts/run.py && ./scripts/exec_in_container.py
+	$ $ python manage.py loaddata $RES_DIR/fixtures/cms_dummy.json
+	$ $ exit
+	$ ./scripts/stop.py
+
+Import Publications
+-------------------
+
+In order to publish a publication on the platform, the following steps are necessary:
+
+#. Using the conversion workflow (`EOASkripts <https://github.molgen.mpg.de/EditionOpenAccess/EOASkripts>`_), produce a Django-XML version of a publication.
+
+#. Import it into the EOA Publication Platform
+
+For the example publication, this process goes as follows:
+
+1. Compile the example
+
+Compile the example file found in `eoa-publication-model <https://github.molgen.mpg.de/EditionOpenAccess/eoa-publication-model>`_. For other examples containing TEI-XML consult https://github.molgen.mpg.de/EditionOpenAccess/EOASkripts#the-tei-workflow-tei---pdf-django-epub::
+
+	$ cd example_import
+	$ git_deps_py --store-dir ../dependencies
+	$ cd dependencies/EOASkripts
+	$ ./scripts/run.py && ./scripts/exec_in_container.py
+	$ $ process_eoa_latex.py input/example/124_eoatex
+	$ $ exit
+	$ ./scripts/stop.py
+	$ cd ../../../
+
+2. Import example into the platform
+
+After the creation of Django-XML, import it into the platform::
+
+    $ mkdir res/publications
+    $ cp -r example_import/EOASkripts/runtime/output/124_eoatex/django res/publications/example
+    $ ./scripts/init.py --skip-db
+    $ ./scripts/run.py && ./scripts/exec_in_container.py
+    $ $ python manage.py publicationimport $RES_DIR/publications/example
+    $ $ exit
+
+Visit http://localhost:8001/ for the main site and http://localhost:8001/studies/124/index.html for the example publication. Go to http://localhost:8001/admin/login/ to access the Django administration pages, using above credentials.
+
+Stop the container with::
+
+  $ ./scripts/stop.py
+
+Configure Project specific Information
+--------------------------------------
+
+In order to tweak the CMS pages, log in to the CMS and edit them.
+
+To change the organisation information (name, logo, ...), edit the files in ``res/custom_config/*`` and then perform ::
+
+  $ ./scripts/init.py --skip-db
+
+To add a logo and a favicon, copy the files into ``res/static/custom_static/``. Files in this directory overwrite default files with the same name::
+
+  $ cp <my_icon> res/static/custom_static/
+  $ ./scripts/init.py --skip-db
+
+
+.. note::
+   The templates expect some pages to exist in the CMS:
+
+   - Introduction Page (id: ``introduction``)
+   - Contact (id: ``contact``)
+   - Imprint (id: ``imprint``)
+
+   Deleting those might break things.
+
+
+Useful commands
+===============
+Run the Webserver::
+
+	$ ./scripts/run.py
+
+The webpage can now be explored in your local browser.
+
+Stop the Webserver::
+
+	$ ./scripts/stop.py
+
+Run Command in the Webserver container::
+
+	$ ./scripts/exec_in_container.py '[ CMD ...]'
+
+Clean the Repository::
+
+	$ ./scripts/exit.py
+
+This should remove all remote repositories and resources not part of this repository.
+Docker images are not deleted though.
+
+Export Data
+===========
+
+In order to export CMS content, run::
+
+	$ ./scripts/run.py && ./scripts/exec_in_container.py 'python manage.py dump_cms'
+	$ cp runtime_data/fixtures/* fixtures/

docs/install_venv.rst

@@ -1,3 +1,95 @@
 =======================================
  Installation with Virtual Environment
 =======================================
+
+As a slightly more lightweight approach, the whole system can also be set up in a Virtual Environment. This solution will definitely be lighter on system resources like disk space and memory.
+
+
+Python packages
+===============
+If not done already, install the following packages (on Linux)::
+
+  sudo apt-get install python3-venv virtualenv
+
+EOA Publication Platform
+========================
+Clone the source files for the publication platform::
+
+  git clone https://github.molgen.mpg.de/EditionOpenAccess/eoa-1.5.git
+
+
+Additional deployment steps
+===========================
+.. note::
+   A small note before you continue, as it is not easy to move a virtual environment after installation.
+
+If you plan to use this installation on a production server, consider the additional steps of creating a separate user and a daemon and running the service in a non-user directory for more security and stability. See :doc:`the main documentation <main:chapters/djangodeploy>`.
+
+
+Create Virtual Environment
+==========================
+You are free to choose a name of your choice here::
+
+  virtualenv -p python3 eoapp_ve
+  cd eoapp_ve
+  source bin/activate
+
+Installation of the system
+--------------------------
+The next steps set up the EOA Publication Platform::
+
+  pip install djangocms-installer lxml
+  djangocms --django-version 2.1 --cms-version stable eoapp
+  pip uninstall djangocms-googlemap
+
+Submodules – Further development planned?
+-----------------------------------------
+If you plan on further developing the submodules of the platform, consider using the following commands for installation. With this, the submodules are located in the ``src`` directory on root level and in version control::
+
+  pip install -e git+https://github.molgen.mpg.de/EditionOpenAccess/django-eoapublications.git#egg=django-eoapublications
+  pip install -e git+https://github.molgen.mpg.de/EditionOpenAccess/django-eoaauthors.git#egg=django-authors
+  pip install -e git+https://github.molgen.mpg.de/EditionOpenAccess/django-eoaseries.git#egg=django-series
+  pip install -e git+https://github.molgen.mpg.de/EditionOpenAccess/django-eoaforthcoming.git#egg=django-forthcoming
+  pip install -e git+https://github.molgen.mpg.de/EditionOpenAccess/django-opds.git#egg=django-opds
+
+Otherwise, use these commands to install them deeper in the system::
+
+  pip install git+https://github.molgen.mpg.de/EditionOpenAccess/django-eoapublications
+  pip install git+https://github.molgen.mpg.de/EditionOpenAccess/django-eoaauthors
+  pip install git+https://github.molgen.mpg.de/EditionOpenAccess/django-eoaseries
+  pip install git+https://github.molgen.mpg.de/EditionOpenAccess/django-eoaforthcoming
+  pip install git+https://github.molgen.mpg.de/EditionOpenAccess/django-opds
+
+Adding the webdesign and templates and settings
+-----------------------------------------------
+If you haven't done so yet, see the :doc:`webdesign documentation <webplat:index>` for installation and usage. For the webdesign, you need the ``app.js`` and ``app.css`` files as well as the ``assets`` directory. After having built these files or obtained them from another source, copy them into the new platform::
+
+  cd <path_to_webdesign_platform>/dist
+  cp -r app.* assets/ <path_to_eoapp_ve>/eoapp/eoapp/static/
+
+Similarly, add the templates and settings from the EOA-1.5 repository::
+
+  cd <path_to_eoapp_ve>
+  rm -r eoapp/eoapp/templates
+  cp -rv <path_to_eoa-1.5>/src/eoa/templates <path_to_eoapp_ve>/eoapp/eoapp/
+  cp <path_to_eoa-1.5>/src/eoa/settings_lite.py <path_to_eoapp_ve>/eoapp/eoapp/settings.py
+  cp <path_to_eoa-1.5>/src/eoa/urls.py <path_to_eoapp_ve>/eoapp/eoapp/
+
+Importing data and setting up the database
+==========================================
+Import some basic CMS pages and settings::
+
+  cd eoapp
+  python manage.py loaddata <path_to_eoa-1.5>/fixtures/cms_dummy.json
+
+Finally, update the database by migrating::
+
+  python manage.py makemigrations
+  python manage.py migrate --run-syncdb
+
+
+Run the server
+==============
+It should now be possible to run a server and access the site through the browser::
+
+  python manage.py runserver 0.0.0.0:8000