diff --git a/AUTHORS.rst b/AUTHORS.rst index dccfdd9af..5cae26d28 100644 --- a/AUTHORS.rst +++ b/AUTHORS.rst @@ -1,214 +1,211 @@ .. This file is part of Invenio. Copyright (C) 2015, 2017 CERN. Invenio 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 2 of the License, or (at your option) any later version. Invenio 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 Invenio; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. In applying this license, CERN does not waive the privileges and immunities granted to it by virtue of its status as an Intergovernmental Organization or submit itself to any jurisdiction. Authors ======= -Invenio is being co-developed by an international collaboration -comprising institutes such as CERN, DESY, EPFL, FNAL, SLAC. - You can contact us at . Active contributors: * Alexander Wagner * Annette Holtkamp * Cornelia Plott * Cristian Bacchi * Dan Michael O. Heggø * Esteban J. G. Gabancho * Evelthon Prodromou * Ferran Jorba * Flavio Costa * Guillaume Lastecoueres * Harris Tzovanakis * Ivan Masár * Jacopo Notarstefano * Javier Martin * Jiri Kuncar * Jocelyne Jerdelet * Johnny Mariéthoz * Kenneth Hole * Kirsten Sachs * Lars Holm Nielsen * Leonardo Rossi * Ludmila Marian * Miguel Martín * Nicolas Harraudeau * Nikolaos Kasioumis * Øystein Blixhavn * Pamfilos Fokianos * Petr Brož * Roman Chyla * Samuele Kaplun * Sebastian Witowski * Stefan Hesselbach * Theodoropoulos Theodoros * Tibor Simko * Thorsten Schwander * Wojciech Ziolek Past contributors: * Adrian Pawel Baran * Adrian-Tudor Panescu * Alberto Pepe * Alessio Deiana * Alexandra Silva * Alper Cinar * Anna Afshar * Antonios Manaras * Artem Tsikiridis * Avraam Tsantekidis * Axel Voitier * Benoit Thiell * Björn Oltmanns * Carmen Alvarez Perez * Christopher Dickinson * Christopher Hayward * Christopher Parker * Daniel Lovasko * Daniel Stanculescu * David Bengoa * Diane Berkovits * Dimitrios Semitsoglou-Tsiapos * Dinos Kousidis * Eamonn Maguire * Eduardo Margallo * Eirini Psallida * Erik Simon * Eric Stahl * Fabio Souto * Federico Poli * Franck Grenier * Frederic Gobry * Fredrik Nygård Carlsen * Gabriel Hase * Georgios Kokosioulis * Georgios Papoutsakis * Gerrit Rindermann * giannistsan * Gilles Louppe * Giovanni Di Milia * Glenn Gard * Graham R. Armstrong * Gregory Favre * Grzegorz Szpura * Guotie * Eduardo Benavidez * Hector Sanchez * Henning Weiler * Ivan Masár * Jaime Garcia Llopis * Jake Cowton * Jan Aage Lavik * Jan Brice Krause * Jan Iwaszkiewicz * Jan Stypka * Jay Luker * Jerome Caffaro * João Batista * Joaquim Rodrigues Silvestre * Jochen Klein * Joe Blaylock * Joe MacMahon * Joël Vogt * Johann C. Rocholl * Jorge Aranda Sumarroca * Juan Francisco Pereira Corral * Julio Pernia Aznar * Juliusz Sompolski * Jurga Girdzijauskaite * Kamil Neczaj * Kevin Bowrin * Kevin M. Flannery * Kevin Sanders * Konstantinos Kostis * Konstantinos Kousidis * Konstantinos Ntemagkos * Krzysztof Jedrzejek * Krzysztof Lis * Kyriakos Liakopoulos * Laura Rueda * Lars Christian Raae * Lewis Barnes * Luke Andrew Smith * Maja Gracco * Marco Neumann * Marios Kogias * Markus Goetz * Marcus Johansson * Marko Niinimaki * Martin Vesely * Mateusz Susik * Mathieu Barras * Miguel Martinez Pedreira * Mikael Karlsson * Mikael Vik * Mike Marino * Mike Sullivan * Minn Soe * Nicholas Robinson * Nikola Yolov * Nikolaos Kalodimas * Nikolay Dyankov * Nino Jejelava * Olivier Canévet * Olivier Serres * Øyvind Østlund * Pablo Vázquez Caderno * Patrick Glauner * Paulo Cabral * Pedro Gaudencio * Peter Halliday * Petros Ioannidis * Piotr Praczyk * Radoslav Ivanov * Raja Sripada * Raquel Jimenez Encinar * Richard Owen * Roberta Faggian * Ruben Pollan * Sami Hiltunen * Samuele Carli * Stamen Todorov Peev * Stephane Martin * Thierry Thomas * Thomas Baron * Thomas Karampelas * Thomas McCauley * Tiberiu Dondera * Tony Ohls * Tony Osborne * Travis Brooks * Trond Aksel Myklebust * Valkyrie Savage * Vasanth Venkatraman * Vasyl Ostrovskyi * Victor Engmark * Yannick Tapparel * Yoan Blanc * Yohann Paris * Željko Kraljević See also THANKS file. diff --git a/README.rst b/README.rst index 068a4c0a3..e9665a838 100644 --- a/README.rst +++ b/README.rst @@ -1,117 +1,58 @@ .. This file is part of Invenio. Copyright (C) 2015, 2016 CERN. Invenio 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 2 of the License, or (at your option) any later version. Invenio 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 Invenio; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. In applying this license, CERN does not waive the privileges and immunities granted to it by virtue of its status as an Intergovernmental Organization or submit itself to any jurisdiction. =================================== Invenio Digital Library Framework =================================== .. image:: https://img.shields.io/travis/inveniosoftware/invenio.svg :target: https://travis-ci.org/inveniosoftware/invenio .. image:: https://img.shields.io/coveralls/inveniosoftware/invenio.svg :target: https://coveralls.io/r/inveniosoftware/invenio .. image:: https://img.shields.io/github/tag/inveniosoftware/invenio.svg :target: https://github.com/inveniosoftware/invenio/releases -.. image:: https://img.shields.io/pypi/dm/invenio.svg - :target: https://pypi.python.org/pypi/invenio - -.. image:: https://badge.waffle.io/inveniosoftware/invenio.svg?label=Status%3A%20ready%20for%20work&title=Issues%20ready%20for%20work - :target: https://waffle.io/inveniosoftware/invenio - .. image:: https://badges.gitter.im/Join%20Chat.svg :target: https://gitter.im/inveniosoftware/invenio?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge -.. image:: https://img.shields.io/github/license/inveniosoftware/invenio.svg - :target: https://github.com/inveniosoftware/invenio/blob/master/COPYING - -Invenio is a free software suite enabling you to run your own digital -library or document repository on the web. The technology offered by -the software covers all aspects of digital library management, from -document ingestion through classification, indexing, and curation up -to document dissemination. Invenio complies with standards such as -the Open Archives Initiative and uses MARC 21 as its underlying -bibliographic format. The flexibility and performance of Invenio make -it a comprehensive solution for management of document repositories of -moderate to large sizes. - -Invenio has been originally developed at CERN to run the CERN document -server, managing over 1,000,000 bibliographic records in high-energy -physics since 2002, covering articles, books, journals, photos, -videos, and more. Invenio is nowadays co-developed by an -international collaboration comprising institutes such as CERN, DESY, -EPFL, FNAL, SLAC and is being used by many more scientific -institutions worldwide. - -We aim at user friendliness and speed. Among the features are: - -- Navigable collection tree - - - Documents organised in collections - - Regular and virtual collection trees - - Customisable portal pages for each collection - - At CERN, over 1,000,000 documents in 700 collections - -- Powerful search engine - - - Specially designed indexes to provide fast search speed - for repositories of up to 3,000,000 records - - Customisable simple and advanced search interfaces - - Combined metadata, fulltext and citation search in one go - - Results clustering by collection - -- Flexible metadata - - - Standard metadata format (MARC) - - Handling articles, books, theses, photos, videos, museum objects - and more - - Customisable batch import and web submission workflows - - Customisable output format display and linking rules - -- Collaborative features and personalisation - - - User-defined document baskets - - User-defined email notification alerts - - Personalised RSS queries - - Sharing documents of interest in user groups - - Peer reviewing and group commenting on documents +Invenio is a digital library framework that enables you to build and run your +own large scale digital repository. -Invenio is free software licenced under the terms of the GNU General -Public Licence (GPL). It is provided on an "as is" basis, in the hope -that it will be useful, but without any warranty. There is a -possibility to get commercial support in case of interest. +Invenio comes in four pre-packaged flavours which are ready to run +out-of-the-box: -Invenio runs on Unix-like systems and requires Python/Flask web application -server, MySQL, PostgreSQL or SQLite database server, Elasticsearch for -information retrieval and Redis for caching. Please consult the INSTALL file for -more information. +- Invenio Integrated Library System (ILS) +- Invenio Institutional Repository (IR) +- Invenio Research Data Management (RDM) +- Invenio Media Archive (MA) -Happy hacking and thanks for flying Invenio. +Invenio is currently powering some of the largest digital repositories in the +world such as: -| Invenio Development Team -| Email: info@inveniosoftware.org -| IRC: #invenio on irc.freenode.net -| Twitter: http://twitter.com/inveniosoftware -| Github: http://github.com/inveniosoftware -| URL: http://inveniosoftware.org +- CERN Document Server and Open Data Repository +- INSPIRE High-Energy Physics Repository +- Caltech Library Catalog +- DESY Publication Database +- Zenodo research data repository diff --git a/docs/aliases.rst b/docs/aliases.rst deleted file mode 100644 index 98c0516ed..000000000 --- a/docs/aliases.rst +++ /dev/null @@ -1,81 +0,0 @@ -.. This file is part of Invenio - Copyright (C) 2014, 2015 CERN. - - Invenio 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 2 of the - License, or (at your option) any later version. - - Invenio 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 Invenio; if not, write to the Free Software Foundation, Inc., - 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. - -:orphan: - -========= - Aliases -========= - -Sometimes *Sphinx* is confused so we have to help him a bit. - - -Jinja2 -====== - -.. py:class:: jinja2.bccache.MemcachedBytecodeCache - - :py:class:`jinja:jinja2.MemcachedBytecodeCache` - -Flask -===== - -.. py:class:: flask.templating.DispatchingJinjaLoader - - A loader that looks for templates in the application and all the blueprint - folders. - -Flask-Assets -============ - -.. py:class:: flask_assets.FlaskResolver - - A subclass of the webassets resolver. - -.. py:class:: flask_assets.ManageAssets - - - A Flask-Script command for managing assets, see: - :ref:`webassets:script-commands` - -Flask-Login -=========== - -.. py:class:: flask_login.UserMixin - - Sorry not valid intersphinx were found for: ``flask_login.UserMixin``. - - -Flask-Script -============ - -.. py:class:: flask_script.commands.Command - - :py:class:`flaskscript:flask_script.Command` - -Webassets -========= - -.. py:class:: webassets.bundle.Bundle - - A webasset :ref:`Bundle ` that combines resources such a - JavaScript or CSS stylesheets. - -.. py:class:: webassets.filter.ExternalTool - - Subclass that helps creating filters that need to run an external - program. diff --git a/docs/architecture/index.rst b/docs/architecture/index.rst deleted file mode 100644 index 89824a083..000000000 --- a/docs/architecture/index.rst +++ /dev/null @@ -1,27 +0,0 @@ -.. This file is part of Invenio - Copyright (C) 2015 CERN. - - Invenio 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 2 of the - License, or (at your option) any later version. - - Invenio 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 Invenio; if not, write to the Free Software Foundation, Inc., - 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. - -============ -Architecture -============ - -.. toctree:: - :maxdepth: 2 - - system-overview - package-anatomy - module-anatomy diff --git a/docs/architecture/module-anatomy-models.rst b/docs/architecture/module-anatomy-models.rst deleted file mode 100644 index 972f6528c..000000000 --- a/docs/architecture/module-anatomy-models.rst +++ /dev/null @@ -1,196 +0,0 @@ -Module models -============= - -Models define a Python-ic interface to relational databases using the -`SQLAlchemy`_ toolkit that *provides a full suite of well -known enterprise-level persistence patterns, designed for efficient and -high-performing database access, adapted into a simple and Pythonic domain -language* [SQLAlchemy2013]_. - -In order to add SQLAlchemy support to our application, the -`Flask-SQLAlchemy`_ extension is used. It provides useful defaults as -well as extra declarative base helpers. We recommend reading -`Official Tutorial` for a full introduction and `Other Tutorial` for -better understanding of ORM concepts. - - -Code structure --------------- - -Our custom bridge contains several custom types and driver hacks for -smoother integration with multiple database engines. The code structure -follows:: - - invenio_ext/sqlalchemy - /engines - mysql.py - __init__.py - expressions.py - types.py - utils.py - - -Before you start writing a new model please take a look at the -``invenio_ext.sqlalchemy.db`` object. It will also make it easier to -understand the following example of a simple model written using SQLAlchemy:: - - # General imports. - from invenio_ext.sqlalchemy import db - - # Create your models here. - - - class User(db.Model): - """Represents a User record.""" - __tablename__ = 'user' - id = db.Column(db.Integer(15, unsigned=True), primary_key=True, - autoincrement=True) - email = db.Column(db.String(255), nullable=False, server_default='', - index=True) - _password = db.Column(db.LargeBinary, name="password", - nullable=False) - note = db.Column(db.String(255), nullable=True) - settings = db.Column(db.MutableDict.as_mutable(db.MarshalBinary( - default_value=lambda: dict(), force_type=dict)), - nullable=True) - nickname = db.Column(db.String(255), nullable=False, server_default='', - index=True) - last_login = db.Column(db.DateTime, nullable=True) - - -All your models used in a module have to be located in ``models.py`` inside -your module package. - -.. note:: If you have any relations between tables use ``ForeignKey`` - definitions and `SQLAlchemy Relationships`_. - - -Quering -------- - -Once you have written models it is possible to change the old way of writing -SQL queries:: - - >>> run_sql("SELECT user.nickname FROM user") - [u.nickname for u in User.query.all()] - # Old Invenio way ... - >>> User.query.values(User.nickname) - >>> db.session.query(User.nickname).all() - >>> db.select([User.nickname]).execute().fetchall() - # All roads lead to Rome ... however some are slower. - - -We also need a WHERE clause in our SQL statements. Let's prepare a statement for -a list with all messages sent by a user:: - - >>> db.select([User.nickname, MsgMESSAGE.subject]).execute().fetchall() - [('admin', 'test1'), - ('admin', 'test2'), - ('jekyll', 'test1'), - ('jekyll', 'test2'), - ... - ('balthasar', 'test1'), - ('balthasar', 'test2')] - - # Something is missing in our query ... - >>> db.select([User.nickname, MsgMESSAGE.subject], User.id==MsgMESSAGE.id_user_from).execute().fetchall() - [('admin', 'test1'), - ('admin', 'test2')] - # This is much better. - -Operators: - -- ``&``, ``and_`` (redefined because of Python operator priorites) -- ``|``, ``or_`` -- ``~``, ``not_`` -- ``==``, ``<=``, ``=>``, ``<``, ``>`` -- ``func.like`` -- text operator ``+``:: - - >>> str(MsgMESSAGE.subject + ': ' + MsgMESSAGE.body) - '"msgMESSAGE".subject || :subject_1 || "msgMESSAGE".body' - # :subject_1 will be replaced by ': ' during query execution - - -Let's use ORM for getting messages sent by "admin":: - - >>> admin = User.query.filter(User.nickname.like('admin')).one() - >>> admin - admin - >>> admin.sent_messages - [From: admin, Subject: body1, - From: admin, Subject: body2] - >>> User.query.filter(User.nickname.like('%a%')) - [admin , - dorian , - balthasar - - -Which brings us to another example where we create ''reusable'' queries -using `db.bindparam` instead of an actual filter value:: - - >>> q = User.query.filter(User.nickname.like(db.bindparam('nickname'))) - >>> q.params({'nickname':'admin'}).one() - admin - >>> q.params({'nickname':'%a%'}).all() - [admin , - dorian , - balthasar ] - - -Subqueries ----------- - -Let's start with simple example:: - - >>> s = db.session.query(User.id).filter(User.nickname.like("%a%")).subquery() - >>> MsgMESSAGE.query.filter(MsgMESSAGE.id_user_from.in_(s)).all() - -You can combine subqueries with the delete statement:: - - >>> sub = db.session.query(UserMsgMESSAGE.id_user_to, UserMsgMESSAGE.id_msgMESSAGE).outerjoin(User, User.id==UserMsgMESSAGE.id_user_to).outerjoin(MsgMESSAGE, UserMsgMESSAGE.id_msgMESSAGE==MsgMESSAGE.id).filter(db.or_(User.id==None, MsgMESSAGE.id==None)).all() - # Find links to not existing messages or users. - >>> db.session.query(UserMsgMESSAGE).filter(db.tuple_(UserMsgMESSAGE.id_user_to, UserMsgMESSAGE.id_msgMESSAGE).in_(sub)).delete(synchronize_session=False) - # Delete messages found in subquery. - -Schema ------- - -When you load all models, you want it to be easy to print create table -statements for these models:: - - >>> for table in db.metadata.tables.values(): print CreateTable(table, on=db.engine.name, bind=db.engine) - - -Similarly, we can print relevant create statements for indexes:: - - >>> [str(CreateIndex(i, on=db.engine.name, bind=db.engine)) for i in table.indexes for table in db.metadata.tables.values() if hasattr(table, 'indexes')] - - -Improve code readability ------------------------- - -Queries and filters can get quite long and some parts are unnecessarily -copied many times. - -Some examples follow:: - - reminder_status = CFG_WEBMESSAGE_STATUS_CODE['REMINDER'] - - db.session.query(UserMsgMESSAGE).join(User, MsgMESSAGE).filter(db.not_(AsBINARY(UserMsgMESSAGE.status.__eq__(reminder_status))) & (UserMsgMESSAGE.id_user_to == 1)).all() - - db.session.query(UserMsgMESSAGE).join(User).filter( - (User.id == MsgMESSAGE.id_user_from) & (UserMsgMESSAGE.id_msgMESSAGE == MsgMESSAGE.id) & - db.not_(AsBINARY(UserMsgMESSAGE.status.__eq__(reminder_status))) & (UserMsgMESSAGE.id_user_to == 1)).all() - - filter_all_message_from_user = lambda uid, status: (User.id == MsgMESSAGE.id_user_from) & (UserMsgMESSAGE.id_msgMESSAGE == MsgMESSAGE.id) & db.not_(AsBINARY(UserMsgMESSAGE.status.__eq__(status))) & (UserMsgMESSAGE.id_user_to == uid) - - - -.. _SQLAlchemy: http://www.sqlalchemy.org/ -.. _SQLAlchemy Relationships: http://docs.sqlalchemy.org/en/latest/orm/extensions/declarative.html#configuring-relationships -.. _Flask-SQLAlchemy: http://Flask-SQLAlchemy.readthedocs.io/ -.. _Official Tutorial: http://docs.sqlalchemy.org/en/latest/orm/tutorial.html -.. _Other Tutorial: http://www.rmunn.com/sqlalchemy-tutorial/tutorial.html - -.. [SQLAlchemy2013] SQLAlchemy website: http://www.sqlalchemy.org/ diff --git a/docs/architecture/module-anatomy-naming.rst b/docs/architecture/module-anatomy-naming.rst deleted file mode 100644 index 9f863927d..000000000 --- a/docs/architecture/module-anatomy-naming.rst +++ /dev/null @@ -1,35 +0,0 @@ -.. This file is part of Invenio - Copyright (C) 2015 CERN. - - Invenio 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 2 of the - License, or (at your option) any later version. - - Invenio 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 Invenio; if not, write to the Free Software Foundation, Inc., - 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. - -Module naming conventions -========================= - -Invenio modules are standalone independent components that implement some -functionality used by the rest of the Invenio ecosystem. The modules provide API -to other modules and use API of other modules. - -A module is usually called: - -1. with plural noun, meaning "database (of things)", for example - ``invenio-records``, ``invenio-tags``, ``invenio-annotations``, - -2. with singular noun, meaning "worker (using things)", for example - ``invenio-checker``, ``invenio-editor``. - -A module may have split its user interface and REST API interface, for example -``invenio-records-ui`` and ``invenio-records-rest``, to clarify dependencies and -offer easy customisation. diff --git a/docs/architecture/module-anatomy-templates.rst b/docs/architecture/module-anatomy-templates.rst deleted file mode 100644 index 1a8f25ec0..000000000 --- a/docs/architecture/module-anatomy-templates.rst +++ /dev/null @@ -1,137 +0,0 @@ -.. This file is part of Invenio - Copyright (C) 2014 CERN. - - Invenio 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 2 of the - License, or (at your option) any later version. - - Invenio 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 Invenio; if not, write to the Free Software Foundation, Inc., - 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. - -Module templates -================ - -`Jinja2`_ is a modern and designer friendly templating language for Python. -We will summarize the adoption of Jinja2 web framework and describe best -practices for writing easily reusable and extendable templates. - -.. note:: Please follow these simple rules when creating new templates to - allow different Invenio installations (CDS, Inspire, ZENODO, ...) to - easily customize templates and keep in sync with updates to templates. - Using these rules will greatly reduce the amount of copy/pasting the - installations will have to do. - - -* ``/views.py``:: - - # ... some where in the blueprint code: - render_template(['/.html'], ctx) - - -* ``/templates//_base.html``:: - - {# - # The base template usually extends the main Invenio template, or perhaps - # a module-specific main template. It contains nearly all the HTML code. - #} - {% extends "page.html" %} - - - {# - # Macros - # * Make template blocks more clear so you don't clutter up a lot of HTML with - # rendering logic - e.g. you wouldn't put your Python code in one big - # function, instead you split it up into small functions with clearly - # defined responsibilities. - # * Macros can be parameterized. - #} - {%- macro action_bar(show_delete=True) %} - {# Macros can be overwritten in a child template, but only calls within the - # child template will call the new macro. Hence, if you just want to - # overwrite the action_bar macro in /.html, you must also - # copy/paste the form_header and form_footer blocks where it's used, - # otherwise the old macro will be used. To avoid this problem, please - # just include a template inside the macro instead. This will allows another - # Invenio installation to overwrite just this part. - #} - {% include "/_action_bar.html"%} - { endmarco %} - - {%- macro render_field(thisfield, with_label=True) %} - {% include "/_render_field.html"%} - {%- endmarco %} - - {# - # Blocks - # * Think of template-blocks as the API which other Invenio installations will - # use to customize the Invenio layout. An Invenio installation can override - # blocks defined in your templates so that they keep their own changes - # to a minimum, and don't copy/paste large parts of the template code. - # * Use blocks liberally - to allow customizations of your template. - # * Add the template block name to the {% endblock %} to increase - # readability of template code. - #} - {% block body %} -
- {%- block form_header scoped %}{{action_bar()}}{% endblock form_header%} - {%- block form_title scoped %}

{{ form._title }}

{% endblock form_title %} - {%- block form_body scoped %} -
- {%- for field in fields %} - {# - # Use the "scoped" parameter, to make variables available inside - # the block. E.g. without the loop variable will not be available - # inside the block. - #} - {%- block field_body scoped %} - {{ render_field(field) }} - {% if loop.last %}
{% endif %} - {%- endblock field_body %} - {%- endfor %} -
- {% endblock form_body %} - {% block form_footer scoped %}{{action_bar(show_delete=False)}}{% endblock form_footer %} -
- {% endblock body %} - - - -* ``/templates//.html``:: - - {# - # The template actually being rendered by the blueprint. It only extends the - # base template. Doing it this way allows an Invenio installation to overwrite - # just the blocks they need instead of having to implement the entire - # template. - #} - {% extends "/_base.html" %} - - - -* ``/templates//.html``:: - - {# - # Here's an example of an Invenio installation which just overwrites the - # necessary template block. - #} - {% extends "/_base.html" %} - - {%- block field_body %} - {%- if field.name == 'awesomefield' %} - {{ render_field(field, class="awesomeness") }} - {% else %} - {{ render_field(field) }} - {%- endif %} - {% if loop.last %}
{% endif %} - {%- endblock field_body %} - - -.. _Flask: http://flask.pocoo.org/ -.. _Jinja2: http://jinja.pocoo.org/2/ diff --git a/docs/architecture/module-anatomy-views.rst b/docs/architecture/module-anatomy-views.rst deleted file mode 100644 index d49f9c856..000000000 --- a/docs/architecture/module-anatomy-views.rst +++ /dev/null @@ -1,36 +0,0 @@ -.. This file is part of Invenio - Copyright (C) 2014 CERN. - - Invenio 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 2 of the - License, or (at your option) any later version. - - Invenio 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 Invenio; if not, write to the Free Software Foundation, Inc., - 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. - -Module views -============ - -If your module has several web interface entry points, such as an admin area and a user area. -``views`` are defined inside their own folder:: - - invenio/modules/ - mymodule/ - views/ - __init__.py - admin.py - user.py - -The ``__init__.py`` file then contains special code to include the views:: - - from .user import blueprint as user_blueprint - from .admin import blueprint as admin_blueprint - - blueprints = [user_blueprint, admin_blueprint] diff --git a/docs/architecture/module-anatomy.rst b/docs/architecture/module-anatomy.rst deleted file mode 100644 index 3916eaca1..000000000 --- a/docs/architecture/module-anatomy.rst +++ /dev/null @@ -1,31 +0,0 @@ -.. This file is part of Invenio - Copyright (C) 2015 CERN. - - Invenio 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 2 of the - License, or (at your option) any later version. - - Invenio 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 Invenio; if not, write to the Free Software Foundation, Inc., - 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. - -.. _module_anatomy: - -============== -Module anatomy -============== - -.. toctree:: - :maxdepth: 2 - - module-anatomy-naming - module-anatomy-structure - module-anatomy-models - module-anatomy-templates - module-anatomy-views diff --git a/docs/architecture/package-anatomy-base.rst b/docs/architecture/package-anatomy-base.rst deleted file mode 100644 index 0fa6be800..000000000 --- a/docs/architecture/package-anatomy-base.rst +++ /dev/null @@ -1,21 +0,0 @@ -.. This file is part of Invenio - Copyright (C) 2015 CERN. - - Invenio 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 2 of the - License, or (at your option) any later version. - - Invenio 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 Invenio; if not, write to the Free Software Foundation, Inc., - 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. - -Invenio base -============ - -FIXME diff --git a/docs/architecture/package-anatomy-extensions.rst b/docs/architecture/package-anatomy-extensions.rst deleted file mode 100644 index f3ff7277b..000000000 --- a/docs/architecture/package-anatomy-extensions.rst +++ /dev/null @@ -1,120 +0,0 @@ -.. This file is part of Invenio - Copyright (C) 2014, 2015 CERN. - - Invenio 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 2 of the - License, or (at your option) any later version. - - Invenio 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 Invenio; if not, write to the Free Software Foundation, Inc., - 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. - -Invenio extensions -================== - -What are extensions and what is their purpose? An extension is a small piece of -code that should ease the integration of a third party library. - -There are many Flask extensions which extend the functionality of the -application in various ways. For instance they can add support for databases, -user authentication & authorization, menu & breadcrumbs and other common tasks. - -All extensions are automatically loaded from the ``EXTENSIONS`` configuration -option list. If they should a function ``setup_app(app)`` or function -accepting ``app`` needs to be specified (e.g. ``foo.bar:init``, -``mymodule:setup``). - -Many Flask extensions can be found in the `Flask Extension Registry`_. Everyone -should check first if there is a usable extension before developing new one. -When developing an extension, follow the `Flask Extension Development`_ -guideline that will help you get your extension running. - -.. _Flask Extension Registry: http://flask.pocoo.org/extensions/ -.. _Flask Extension Development: http://flask.pocoo.org/docs/extensiondev/ - -Plugging an Existing Extension ------------------------------- - -All extensions are located in a package called ``flask_something`` -where "something" is the name of the extension you want to bridge. -So for example if you plan to add support for an extension named -`login`, you would name your extension's package ``invenio.ext.login``. - -Alternatively, if the extension only reads configuration from -``current_app.config``, you can just list in ``EXTENSIONS`` option -as ``flask_something:Something``, where ``Something`` has to accept -an application object as first argument:: - - class Something(object): - def __init__(self, app, optional=None): - pass - -So what do extensions actually look like? An extension has to ensure -that it works with multiple Flask application instances at the same time. - - -Code structure --------------- - -So let's get started with creating such an extension bridge. This example -bridge will provide very basic support for `Flask Login`_. - -First we'll create the following folder structure:: - - invenio/ext/login/ - __init__.py - legacy_user.py - README - -Here's the contents of the most important files: - -* ``__init__.py`` contains ``setup_app`` function: - -.. code-block:: python - - from .legacy_user import UserInfo - - def setup_app(app): - """Setup login extension.""" - - # Let's create login manager. - _login_manager = LoginManager(app) - _login_manager.login_view = app.config.get('CFG_LOGIN_VIEW', - 'webaccount.login') - _login_manager.anonymous_user = UserInfo - - @_login_manager.user_loader - def _load_user(uid): - """ - Function should not raise an exception if uid is not valid - or User was not found in database. - """ - return UserInfo(int(uid)) - - return app - -* ``legacy_user.py`` contains implementation of the ``UserMixin`` object: - -.. code-block:: python - - from flask_login import UserMixin - from werkzeug.datastructures import CallbackDict, CombinedMultiDict - - class UserInfo(CombinedMultiDict, UserMixin): - - """ - This provides legacy implementations for methods that Flask-Login - and Invenio 1.x expect user objects to have. - """ - - def __init__(self, uid=None, force=False): - ... - - -.. _Flask Login: https://flask-login.readthedocs.io/en/latest/ diff --git a/docs/architecture/package-anatomy-modules.rst b/docs/architecture/package-anatomy-modules.rst deleted file mode 100644 index ec09d7625..000000000 --- a/docs/architecture/package-anatomy-modules.rst +++ /dev/null @@ -1,56 +0,0 @@ -.. This file is part of Invenio - Copyright (C) 2014 CERN. - - Invenio 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 2 of the - License, or (at your option) any later version. - - Invenio 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 Invenio; if not, write to the Free Software Foundation, Inc., - 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. - -Invenio modules -=============== - -Modules are application components that can be used within an application or -across aplications. They can contain :ref:`SQLAlchemy ` -models, :ref:`Flask view `, :py:class:`Jinja2 templates -` and other pluggable objects. - -Discovery of modules is done based on the ``PACKAGES`` configuration parameter, -where the `*` wildcard character is supported at the end of the -package path after the last dot (e.g. ``foo.bar.something.*``). - -Flask uses a concept of *blueprints* for making application components and -supporting common patterns within an application or across applications. -Blueprints can greatly simplify how large applications work and provide a -central means for Flask extensions to register operations on applications. A -:py:class:`~flask.Blueprint` object works similarly to a -:py:class:`~flask.Flask` application object, but it is not actually an -application. Rather it is a *blueprint* of how to construct or extend an -application. - -Blueprints in Flask are intended for these cases: - -* Factor an application into a set of blueprints. This is ideal for - larger applications; a project could instantiate an application object, - initialize several extensions, and register a collection of blueprints. -* Register a blueprint on an application at a URL prefix and/or subdomain. - Parameters in the URL prefix/subdomain become common view arguments - (with defaults) across all view functions in the blueprint. -* Register a blueprint multiple times on an application with different URL - rules. -* Provide template filters, static files, templates, and other utilities - through blueprints. A blueprint does not have to implement applications - or view functions. -* Register a blueprint on an application for any of these cases when - initializing a Flask extension. - -For more information on Invenio modules, see the next section about "module -anatomy". diff --git a/docs/architecture/package-anatomy-utilities.rst b/docs/architecture/package-anatomy-utilities.rst deleted file mode 100644 index a8f3b3937..000000000 --- a/docs/architecture/package-anatomy-utilities.rst +++ /dev/null @@ -1,21 +0,0 @@ -.. This file is part of Invenio - Copyright (C) 2015 CERN. - - Invenio 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 2 of the - License, or (at your option) any later version. - - Invenio 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 Invenio; if not, write to the Free Software Foundation, Inc., - 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. - -Invenio utilities -================= - -FIXME diff --git a/docs/architecture/package-anatomy.rst b/docs/architecture/package-anatomy.rst deleted file mode 100644 index 2067bdf75..000000000 --- a/docs/architecture/package-anatomy.rst +++ /dev/null @@ -1,28 +0,0 @@ -.. This file is part of Invenio - Copyright (C) 2015 CERN. - - Invenio 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 2 of the - License, or (at your option) any later version. - - Invenio 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 Invenio; if not, write to the Free Software Foundation, Inc., - 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. - -=============== -Package anatomy -=============== - -.. toctree:: - :maxdepth: 2 - - package-anatomy-base - package-anatomy-extensions - package-anatomy-utilities - package-anatomy-modules diff --git a/docs/architecture/system-overview.rst b/docs/architecture/system-overview.rst deleted file mode 100644 index 406a36f5d..000000000 --- a/docs/architecture/system-overview.rst +++ /dev/null @@ -1,506 +0,0 @@ -.. This file is part of Invenio - Copyright (C) 2015, 2016 CERN. - - Invenio 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 2 of the - License, or (at your option) any later version. - - Invenio 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 Invenio; if not, write to the Free Software Foundation, Inc., - 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. - -System overview -=============== - - -Invenio v3.x ------------- - -.. admonition:: CAVEAT LECTOR - - Invenio v3.0 alpha is a bleeding-edge developer preview version. - -Invenio v3.0 build on top of `Flask`_ web development framework, using `Jinja2`_ -template engine, `SQLAlchemy`_ Object Relational Mapper, `JSONSchema`_ data -model, `PostgreSQL`_ database for persistence, and `Elasticsearch`_ for -information retrieval. - -.. _Flask: http://flask.pocoo.org/ -.. _Jinja2: http://jinja.pocoo.org/docs/ -.. _SQLAlchemy: http://www.sqlalchemy.org/ -.. _JSONSchema: http://json-schema.org/ -.. _PostgreSQL: http://www.postgresql.org/ -.. _Elasticsearch: https://www.elastic.co/products/elasticsearch - -Invenio's architecture is modular. The code base is split into more than 50 -independent components that are `released independently on PyPI -`_. -This ensures strict separation of components that talk among themselves over API -and permits rapid development of independent components by independent teams. - -Invenio compontents, named *modules*, can be roughly split in three categories: - -1. **base modules** provide interfaces to the Flask ecosystem, the Database, and - other system tools and technologies that the Invenio ecosystem uses. Example: - ``Invenio-Celery`` that talks to the Celery worker system. - -2. **core feature modules** provide most common functionality that each digital - library instance is likely interested in using. Example: ``Invenio-Records`` - provide record object store. - -3. **additional feature modules** offer additional functionality suitable for - various particular use cases, such as the Integrated Library System, the - Multimedia Store, or the Data Repository. Example: ``Invenio-Circulation`` - offers circulation and holdings capabilities. - -Here is a basic bird-eye overview of available Invenio components and their -dependencies: (*work in progress*) - -.. graphviz:: - - digraph invenio3 { - size="20.0 20.0"; - ratio="compress"; - - // helper floors - node [shape=plaintext,style=invis]; - { - Floor9 -> Floor8 [style=invis]; - Floor8 -> Floor7 [style=invis]; - Floor7 -> Floor6 [style=invis]; - Floor6 -> Floor5 [style=invis]; - Floor5 -> Floor4 [style=invis]; - Floor4 -> Floor3 [style=invis]; - Floor3 -> Floor2 [style=invis]; - Floor2 -> Floor1 [style=invis]; - Floor1 -> Floor0 [style=invis]; - } - - // invenio tools family - node [shape=ellipse,style=dotted]; - Elasticsearch; - "JSON Schema"; - MySQL; - PostgreSQL; - FS; - Drive; - Dropbox; - S3; - " Celery "; - Flask; - - // invenio base plate family - node [shape=box,style=filled]; - Access; - Admin; - Assets; - Base; - Celery -> " Celery "; - Config; - DB -> MySQL; - DB -> PostgreSQL; - I18N; - JSONSchemas -> "JSON Schema"; - Logging; - REST; - Theme; - Upgrader -> DB; - - // invenio search family - node [shape=box,style=filled, color=green]; - "Records-UI" -> Records; - "Records-REST" -> Records; - "Records-REST" -> PIDStore; - Records -> DB; - "Search-UI" -> Search; - Search -> Records; - "Records-REST" -> Search; - PIDStore -> Records; - PIDStore -> DB; - node [shape=ellipse,style=filled,color=grey]; - "Search-UI" -> "Query-Parser" ; - "Search-UI" -> unAPI; - node [shape=ellipse,style=dotted,color=black]; - Search -> Elasticsearch; - - // invenio deposit family - node [shape=box,style=filled, color=red]; - "Deposit-UI" -> Deposit; - "Deposit-REST" -> Deposit; - Deposit -> Workflows; - Deposit -> Knowledge; - Deposit -> Sequencegenerator; - Workflows -> Records; - Workflows -> Documents; - - // invenio accounts family - node [shape=box,style=filled, color="0.5 0.5 1.0"]; - "Profiles-UI" -> Profiles; - "Profiles-REST" -> Profiles; - "Groups-UI" -> Groups; - "Groups-REST" -> Groups; - Profiles -> Access; - Profiles -> Accounts; - Accounts -> Access; - Groups -> Accounts; - - // invenio helpers family - node [shape=ellipse,style=filled,color=grey]; - Documents; - Cloudconnector; - Testing; - Utils; - Ext; - Webhooks; - Redirector; - - // invenio OAIS family - node [shape=box,style=filled,color=orange]; - "OAIS-Audit-Store" -> DB; - "OAIS-SIP-Store" -> DB; - "OAIS-AIP-Store" -> Cloudconnector; - "OAIS-DIP-Store" -> DB; - Archiver; - Deposit -> "OAIS-SIP-Store"; - Workflows -> "OAIS-SIP-Store"; - Records -> Archiver; - Documents -> Archiver; - Archiver -> "OAIS-AIP-Store"; - Records -> "OAIS-Audit-Store"; - - // invenio add-ons family - node [shape=box, style=filled, color=yellow]; - Alerts -> Records; - Annotations -> Records; - Annotations -> Profiles; - Classifier -> Records; - Client -> "Records-REST"; - Client -> "Groups-REST"; - Client -> "Profiles-REST"; - Client -> "Deposit-REST"; - Documents -> Cloudconnector; - Documents -> FS; - Cloudconnector -> Dropbox; - Cloudconnector -> Drive; - Cloudconnector -> S3; - Collections -> Records; - Comments -> Records; - Comments -> Profiles; - Communities -> Collections; - Communities -> Groups; - Communities -> Profiles; - Deposit -> Documents; - Deposit -> Records; - Deposit -> PIDStore; - Documents -> Records; - Formatter -> Records; - Formatter -> "OAIS-DIP-Store"; - Records -> JSONSchemas; - News -> Theme; - OAIHarvester -> DB; - OAIHarvester -> Workflows; - OAIHarvester -> Records; - OAuthClient -> Accounts; - OAuth2Server -> Accounts; - Pages -> Theme; - Previewer -> Records; - Previewer -> "Previewer-ISPY"; - Editor -> "Records-REST"; - Checker -> "Records-REST"; - Merger -> "Records-REST"; - Statistics; - Tags -> Records; - Tags -> Profiles; - - // invenio ILS family - node [shape=box, style=filled, color=purple]; - "Circulation-UI" -> Circulation; - "Circulation-REST" -> Circulation; - "Acquisition-UI" -> Acquisition; - "Acquisition-REST" -> Acquisition; - Client -> "Circulation-REST"; - Client -> "Acquisition-REST"; - Circulation -> Records; - Circulation -> Accounts; - Acquisition -> Records; - Acquisition -> Accounts; - - - // invenio end user - node [shape=plaintext, color=white]; - Users; - Users -> "Deposit-UI"; - Users -> "Search-UI"; - Users -> "Records-UI"; - Users -> "Circulation-UI"; - Users -> "Acquisition-UI"; - - // floor 0 - { - rank = same; - Floor0; - Elasticsearch; - MySQL; - PostgreSQL; - " Celery "; - "JSON Schema"; - Flask; - Drive; - Dropbox; - S3; - FS; - } - - // floor 1 - { - rank = same; - Floor1; - Access; - Admin; - Assets; - Base; - Celery; - Config; - DB; - I18N; - JSONSchemas; - Logging; - Theme; - REST; - Upgrader; - DB; - Testing; - Utils; - Ext; - Webhooks; - Redirector; - } - - // floor 8 - { - rank = same; - Floor8; - "Records-UI"; - "Records-REST"; - "Deposit-UI"; - "Deposit-REST"; - "Search-UI"; - "Profiles-UI"; - "Profiles-REST"; - "Groups-UI"; - "Groups-REST"; - "Circulation-UI"; - "Circulation-REST"; - "Acquisition-UI"; - "Acquisition-REST"; - } - // floor 9 - { - rank = same; - Floor9; - Client; - Users; - } - - } - -For further information, see :ref:`module_anatomy` and :ref:`module_list` -sections. - -Invenio v2.x ------------- - -Invenio v2.x was a transitional release series combining legacy code base -(Invenio v1.x) with new technology (Flask etc as used in Invenio v3.x). - -Invenio v1.x ------------- - -Invenio consists of several more or less independent modules with precisely -defined functionality. The general criterion for module names is to use the -"Bib" prefix to denote modules that work more with the bibliographic data, and -the "Web" prefix to denote modules that work more with the Web interface. (The -difference is of course blurred in some cases, as in the case of search engine -that has got a web interface but searches bibliographic data.) - -.. image:: /_static/modules-overview-diagram.jpeg - -Follows a brief description of what each module does. - -- BibCheck permits administrators and library cataloguers to automate various - kind of tests on the metadata to see whether the metadata comply with quality - standards. For example, that certain metadata fields are of a certain length, - that they have numeric content, that they must not be present when other field - exists, that their content is governed by an authority base depending on - values of other fields, etc. The module can report its findings or can even - automatically correct some kind of errors. - -- BibClassify allows automatic extraction of keywords from fulltext documents, - based on the frequency of specific terms, taken from a controlled vocabulary. - Controlled vocabularies can be expressed as simple text thesauri or as - structured, RDF-compliant, taxonomies, to allow a semantic classification. - -- BibConvert allows metadata conversion from any structured or semi-structured - proprietary format into any other format, typically the MARC XML that is - natively used in Invenio. Nevertheless the input and output formats are fully - configurable and have been tested on data importations from more than one - hundred data sources. The power of this utility lies in the fact that no - structural attributes of data source are presumed, but they are defined in an - extensive data source configuration. Inevitably, this leads to a high - complexity of the BibConvert configuration language. Most frequent - configurations are provided with the Invenio distribution, such as a sample - configuration from Qualified Dublin Core into the MARCXML. In general the - BibConvert configuration consists from the source data descriptions and target - data descriptions. The processor then analyzes and parses the input data and - creates the resulting data structure, similarly as the XSLT processor would - do. Typically the BibConvert is aimed at usage for input data that do not - dispose of an XML representation. The source data is required to be structured - or semi-structured, (i.e. not expressed in natural language that is a subject - of information extraction task) and its processing involves several steps - including record separation and field extraction upto transformation of source - field values and their formatting. - -- BibEdit permits one to edit the metadata via a Web interface. - -- BibFormat is in charge of formatting the bibliographic metadata in numerous - ways. This truly enables the separation of data content administration and - formatting layout. BibFormat can act in the background and format the records - when needed, or can preformat records for some often used outputs, such as the - brief format used when displaying search results. The BibFormat settings can - be administered either through a user-friendly web interface, or directly by - editing human-readable configuration files. - -- OAIHarvest represents the OAi-PMH compatible harvester allowing the repository - to gather metadata from fellow OAi-compliant repositories and the OAi-PMH - repository management. Repository is built directly on top of the database and - disposes of an OAi repository manager that allows to perform the - administrative tasks on the repository aside from the principal generic data - administration module. The database can be partially or completely open for - harvesting in the scope of the OAi-PMH protocol. In this case, all data is - provided in raw form, where the semantics of individual tags is indicated - uniquely by the MARC21 naming convention. This is particularly interesting for - institutes that are specialized in cross-archive and cross-disciplinary - services provision, as for example the ARC service provider. - -- BibIndex module takes care of the indexation of metadata, references and full - text files. Two kinds of indexes -- word and phrase index -- are being - maintained. The user can define several logical indexes (e.g. author index, - title index, etc.) and the correspondence of which physical MARC21 metadata - tag goes into which logical field index. An index consists of two parts: (i) a - forward index listing various words (or phrases) found in the given field, - with the set of record identifiers where the given word can be found; and (ii) - a reverse index listing record identifiers, with the set of words of the given - record that go to the forward index. Such a two-part indexing technique allows - one to rapidly update only those words that have changed in the input metadata - record. The indexes were designed with the aim to provide fast user-response - search times and are faster than native MySQL (full text) indexes. - -- BibMatch permits to filter input XML files against the database content, - attempting to match records via certain criteria, for example to avoid - doubly-inputted records. - -- BibRank permits to set up various ranking criteria that will be used later by - the search engine. For example, ranking by the word frequency, or by some - metadata tag value such as journal name by means of the journal impact factor - knowledge base, or even by the number of downloads of a particular paper. Note - that BibRank is independent of BibIndex. - -- BibSched The bibliographic task scheduler is central unit of the system that - allows all other modules to access the bibliographic database in a controlled - manner, preventing sharing violation threats and assuring the coherent - execution of the database update tasks. The module comes with an - administrative interface that allows to monitor the task queue including - various possibilities of a manual intervention, for example to re-schedule - queued tasks, change the task order, etc. - -- BibUpload allows to load the new bibliographic data into the database. To - effectuate this task the data must be a well-formed XML file that complies - with the current metadata tag selection schema. Usually, the properly - structured input files of BibUpload come from the BibConvert utility. - -- ElmSubmit is an email submission gateway that permits for automatic document - uploads from trusted sources via email. (Usually web submission or harvesting - is preferred.) - -- MiscUtil is a collection of miscellaneous utilities that other modules are - using, like the international messages, etc. - -- WebAccess module is responsible for granting access to users for performing - various actions within the system. A Role-Based Access Control (RBAC) - technique is used, where users belong to several groups according to their - role in the system. Each user group can be granted to perform certain actions - depending on possible one more action arguments. WebAccess is presently used - mainly for the administrative interface. There are basically two kinds of - actions: (i) configuration of administrative modules and (ii) running - administrative tasks. - -- WebAlert module allows the end user to be alerted whenever a new document - matching her personal criteria is inserted into the database. The criteria - correspond to a typical user query as if it would be done via the search - interface. For example, a user may want to get notified whenever a new - document containing certain words, or of a certain subject, is inserted. A - user may create several alerts with a daily, weekly, or a monthly frequency. - The results of alert searches are either sent back to the user by email or can - also be stored into her baskets. - -- WebBasket module enables the end user of the system to store the documents she - is interested in in a personal basket or a personal shelf. The concept is - similar to popular shopping carts. One user may own several baskets. A basket - can be either private or public, allowing a simple document sharing mechanism - within a group. - -- WebComment provides a community-oriented tool to rank documents by the readers - or to share comments on the documents by the readers. Integrated with the - group-aware WebBasket, WebGroup, WebMessage tools, WebComment is at the heart - of the social network features of the Invenio software. - -- WebHelp presents some global user-level, admin-level, and hacker-level - documenation on Invenio. The module-specific documentation is included within - each particular module. - -- WebMessage permits the communication between (possibly anonymous) end users - via web message boards, to invite readers to join the groups, etc. - -- WebSearch module handles user requests to search for a certain words or - phrases in the database. Two types of searching can be performed: a word - search or a phrase search. The system allows for complex boolean queries, - regular expression searching, or a combined metadata, references and full text - file searching in one go. Users have a possibility to browse for present index - terms. If no direct match could have been found with the user-typed query - pattern, the system proposes alternative matches as a search guidance. The - search indexes were designed to provide fast response times for middle-sized - data collections of up to 106 records. The metadata corpus is organized into - metadata collections that are directly accessible through the browse function, - similarly to the popular concept of Web Directories. Orthogonal views on the - document corpus are enabled in the search interface via a concept of virtual - collections: for example, a document may be classified both according to its - type (e.g. preprint, book) and according to its Dewey decimal classification - number. Such a flexible organization views allows for the creation of easy - navigation schemata to the end users. - -- WebSession is a session and user management module that permits to - differentiate between users. Useful for personalization of the interface and - services like personal baskets and alerts. - -- WebStat is a configurable system that permits to gather statistics about the - health of the server, the usage of the system, as well as about some - particular system features. - -- WebStyle is a library of design-related modules that defines look and feel of - Invenio pages. - -- WebSubmit is a comprehensive submission system allowing authorized individuals - (authors, secretaries and repository maintenance staff) to submit individual - documents into the system. The submission system disposes of a flow-control - mechanism that assures the data approval by authorized units. In total there - are several different exploitable submission schemas at a disposal, including - an automated full text document conversion from various textual and image - formats. This module also disposes of information extraction functionality, - focusing on bibliographic entities such as references, authors, keywords or - other implicit metadata. diff --git a/docs/authors.rst b/docs/community/authors.rst similarity index 96% rename from docs/authors.rst rename to docs/community/authors.rst index 4339a586c..50d13cc1a 100644 --- a/docs/authors.rst +++ b/docs/community/authors.rst @@ -1,25 +1,24 @@ .. This file is part of Invenio. Copyright (C) 2015 CERN. Invenio 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 2 of the License, or (at your option) any later version. Invenio 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 Invenio; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. In applying this license, CERN does not waive the privileges and immunities granted to it by virtue of its status as an Intergovernmental Organization or submit itself to any jurisdiction. - -.. include:: ../AUTHORS.rst +.. include:: ../../AUTHORS.rst diff --git a/docs/community/blogs.rst b/docs/community/blogs.rst deleted file mode 100644 index d29eb331a..000000000 --- a/docs/community/blogs.rst +++ /dev/null @@ -1,25 +0,0 @@ -.. This file is part of Invenio - Copyright (C) 2015 CERN. - - Invenio 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 2 of the - License, or (at your option) any later version. - - Invenio 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 Invenio; if not, write to the Free Software Foundation, Inc., - 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. - -Blogs -===== - -There are several Invenio developers blogging about (not only) Invenio related -matters: - -- ``_ - diff --git a/docs/community/chatrooms.rst b/docs/community/chatrooms.rst deleted file mode 100644 index e753b8e53..000000000 --- a/docs/community/chatrooms.rst +++ /dev/null @@ -1,40 +0,0 @@ -.. This file is part of Invenio - Copyright (C) 2015, 2016 CERN. - - Invenio 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 2 of the - License, or (at your option) any later version. - - Invenio 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 Invenio; if not, write to the Free Software Foundation, Inc., - 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. - -Chat rooms -========== - -Gitter ------- - -We use Gitter for both personal and group chat. Our main chat room is: - -- ``_ - -There are several other chat rooms for individual repositories. - -Google Hangouts ---------------- - -We used to use "Invenio Developers" hangout, but it fell out of use. People are -mostly on Gitter nowadays. - -IRC ---- - -We used to use ``#invenio`` IRC channel at ``irc.freenode.net``, but it fell out -of use. People are mostly on Gitter nowadays. diff --git a/docs/community/code-of-conduct.rst b/docs/community/code-of-conduct.rst index db3c16cba..14ff62a4a 100644 --- a/docs/community/code-of-conduct.rst +++ b/docs/community/code-of-conduct.rst @@ -1,118 +1,117 @@ .. This file is part of Invenio Copyright (C) 2015 CERN. Invenio 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 2 of the License, or (at your option) any later version. Invenio 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 Invenio; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. .. _code-of-conduct: -================= - Code of Conduct -================= +Code of Conduct +=============== We endorse the `Python Community Code of Conduct `_: The Invenio community is made up of members from around the globe with a diverse set of skills, personalities, and experiences. It is through these differences that our community experiences great successes and continued growth. When you're working with members of the community, we encourage you to follow these guidelines which help steer our interactions and strive to keep Invenio a positive, successful, and growing community. A member of the Invenio community is: 1. **Open.** Members of the community are open to collaboration, whether it's on RFCs, patches, problems, or otherwise. We're receptive to constructive comment and criticism, as the experiences and skill sets of other members contribute to the whole of our efforts. We're accepting of all who wish to take part in our activities, fostering an environment where anyone can participate and everyone can make a difference. 2. **Considerate.** Members of the community are considerate of their peers -- other Invenio users. We're thoughtful when addressing the efforts of others, keeping in mind that often times the labor was completed simply for the good of the community. We're attentive in our communications, whether in person or online, and we're tactful when approaching differing views. 3. **Respectful.** Members of the community are respectful. We're respectful of others, their positions, their skills, their commitments, and their efforts. We're respectful of the volunteer efforts that permeate the Invenio community. We're respectful of the processes set forth in the community, and we work within them. When we disagree, we are courteous in raising our issues. Overall, we're good to each other. We contribute to this community not because we have to, but because we want to. If we remember that, these guidelines will come naturally. We recommend the "egoless" programming principles (Gerald Weinberg, `The Psychology of Computer Programming `_, 1971): 1. **Understand and accept that you will make mistakes.** The point is to find them early, before they make it into production. Fortunately, except for the few of us developing rocket guidance software at JPL, mistakes are rarely fatal in our industry, so we can, and should, learn, laugh, and move on. 2. **You are not your code.** Remember that the entire point of a review is to find problems, and problems will be found. Don't take it personally when one is uncovered. 3. **No matter how much "karate" you know, someone else will always know more.** Such an individual can teach you some new moves if you ask. Seek and accept input from others, especially when you think it's not needed. 4. **Don't rewrite code without consultation.** There's a fine line between "fixing code" and "rewriting code." Know the difference, and pursue stylistic changes within the framework of a code review, not as a lone enforcer. 5. **Treat people who know less than you with respect, deference, and patience.** Nontechnical people who deal with developers on a regular basis almost universally hold the opinion that we are prima donnas at best and crybabies at worst. Don't reinforce this stereotype with anger and impatience. 6. **The only constant in the world is change.** Be open to it and accept it with a smile. Look at each change to your requirements, platform, or tool as a new challenge, not as some serious inconvenience to be fought. 7. **The only true authority stems from knowledge, not from position.** Knowledge engenders authority, and authority engenders respect – so if you want respect in an egoless environment, cultivate knowledge. 8. **Fight for what you believe, but gracefully accept defeat.** Understand that sometimes your ideas will be overruled. Even if you do turn out to be right, don't take revenge or say, "I told you so" more than a few times at most, and don't make your dearly departed idea a martyr or rallying cry. 9. **Don't be "the guy in the room".** Don't be the guy coding in the dark office emerging only to buy cola. The guy in the room is out of touch, out of sight, and out of control and has no place in an open, collaborative environment. 10. **Critique code instead of people** – be kind to the coder, not to the code. As much as possible, make all of your comments positive and oriented to improving the code. Relate comments to local standards, program specs, increased performance, etc. diff --git a/docs/community/contribution-guide.rst b/docs/community/contribution-guide.rst new file mode 100644 index 000000000..c3b1c3cb6 --- /dev/null +++ b/docs/community/contribution-guide.rst @@ -0,0 +1,2 @@ +Contribution guide +================== diff --git a/docs/community/forum.rst b/docs/community/forum.rst deleted file mode 100644 index a63aeb882..000000000 --- a/docs/community/forum.rst +++ /dev/null @@ -1,24 +0,0 @@ -.. This file is part of Invenio - Copyright (C) 2015 CERN. - - Invenio 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 2 of the - License, or (at your option) any later version. - - Invenio 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 Invenio; if not, write to the Free Software Foundation, Inc., - 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. - -Forum -===== - -Every Monday at 16:00 CEST we get together for an hour of live discussions. We -call it the "Invenio Developer Forum". It is possible to join via -videoconference. Please see dedicated `Invenio Developer Forum -`_ website with instructions and agenda. diff --git a/docs/community/mailinglists.rst b/docs/community/getting-involved.rst similarity index 69% rename from docs/community/mailinglists.rst rename to docs/community/getting-involved.rst index 7edf18a10..02239a5dd 100644 --- a/docs/community/mailinglists.rst +++ b/docs/community/getting-involved.rst @@ -1,70 +1,82 @@ -.. This file is part of Invenio - Copyright (C) 2015 CERN. +Getting involved +================ - Invenio 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 2 of the - License, or (at your option) any later version. +Communication channels +---------------------- - Invenio 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. +Chatrooms +~~~~~~~~~ +We use Gitter for both personal and group chat. Our main chat room is: - You should have received a copy of the GNU General Public License - along with Invenio; if not, write to the Free Software Foundation, Inc., - 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. +- ``_ -Mailing lists -============= -There are several Invenio-related mailing lists that you can subscribe -to or read the archives of. +GitHub +~~~~~~ +Most of the developer communication is happening nowadays on GitHub, not on the +mailing lists. You are stroungly encouraged to join +``_ team and watch +notifications from various ``_ organisation +repositories of interest. + + +Invenio Developer Forum +~~~~~~~~~~~~~~~~~~~~~~~ +Every Monday at 16:00 CET/CEST we get together for an hour of live discussions. +We call it the "Invenio Developer Forum". It is possible to join via +videoconference. Please see dedicated `Invenio Developer Forum +`_ website with instructions and agenda. + + +Invenio User Group Workshop +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Twitter +~~~~~~~ +The official Twitter account for Invenio software is used mostly for announcing +new releases and talks at conferences: + +- ``_ + +inveniosoftware.org +~~~~~~~~~~~~~~~~~~~ + + +Mailing lists +~~~~~~~~~~~~~ ``project-invenio-announce@cern.ch`` ------------------------------------- Low-volume read-only moderated mailing list to announce new Invenio releases and other major news concerning the project. Every Invenio user is strongly encouraged to subscribe to this list. - `p-i-a (un)subscribe `_ - `p-i-a new archives `_ - `p-i-a old archives `_ - `p-i-a very old archives `_ ``project-invenio-general@cern.ch`` ------------------------------------ Possibly high-volume mailing list, intended for discussion among users and administrators of Invenio instances. - `p-i-g (un)subscribe `_ - `p-i-g new archives `_ - `p-i-g old archives `_ - `p-i-g very old archives `_ ``project-invenio-devel@cern.ch`` ---------------------------------- Possibly high-volume mailing list, intended for discussion among Invenio developers and hackers. - `p-i-d (un)subscribe `_ - `p-i-d new archives `_ - `p-i-d old archives `_ - `p-i-d very old archives `_ Note that all the mailing lists are also archived (as of the 20th of July, 2011) on `The Mail Archive `__. As soon as possible we will upload there also all the previous historical archives. - -``github.com/inveniosoftware`` ------------------------------- - -Most of the developer communication is happening nowadays on GitHub, not on the -mailing lists. You are stroungly encouraged to join -``_ team and watch -notifications from various ``_ organisation -repositories of interest. diff --git a/docs/community/index.rst b/docs/community/index.rst deleted file mode 100644 index 2e814750e..000000000 --- a/docs/community/index.rst +++ /dev/null @@ -1,32 +0,0 @@ -.. This file is part of Invenio - Copyright (C) 2015 CERN. - - Invenio 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 2 of the - License, or (at your option) any later version. - - Invenio 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 Invenio; if not, write to the Free Software Foundation, Inc., - 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. - -.. _community: - -========= -Community -========= - -.. toctree:: - :maxdepth: 2 - - code-of-conduct - mailinglists - chatrooms - forum - twitter - blogs diff --git a/docs/license.rst b/docs/community/license.rst similarity index 100% rename from docs/license.rst rename to docs/community/license.rst diff --git a/docs/community/maintainers-guide/branches.rst b/docs/community/maintainers-guide/branches.rst new file mode 100644 index 000000000..0089bef49 --- /dev/null +++ b/docs/community/maintainers-guide/branches.rst @@ -0,0 +1,2 @@ +Understanding branches +====================== diff --git a/docs/community/maintainers-guide/index.rst b/docs/community/maintainers-guide/index.rst new file mode 100644 index 000000000..c87f1971d --- /dev/null +++ b/docs/community/maintainers-guide/index.rst @@ -0,0 +1,12 @@ +Maintainer's guide +================== + +.. todo:: Fill with new proposal + +.. toctree:: + :maxdepth: 2 + + overview + releasing + setup-repository + branches diff --git a/docs/community/maintainers-guide/overview.rst b/docs/community/maintainers-guide/overview.rst new file mode 100644 index 000000000..802d34147 --- /dev/null +++ b/docs/community/maintainers-guide/overview.rst @@ -0,0 +1,2 @@ +Overview +======== diff --git a/docs/community/maintainers-guide/releasing.rst b/docs/community/maintainers-guide/releasing.rst new file mode 100644 index 000000000..5d132dae1 --- /dev/null +++ b/docs/community/maintainers-guide/releasing.rst @@ -0,0 +1,2 @@ +Making a release +================ diff --git a/docs/community/maintainers-guide/setup-repository.rst b/docs/community/maintainers-guide/setup-repository.rst new file mode 100644 index 000000000..9e2e2d6cd --- /dev/null +++ b/docs/community/maintainers-guide/setup-repository.rst @@ -0,0 +1,2 @@ +How to setup a new repository +============================= diff --git a/docs/introduction/releases.rst b/docs/community/releases.rst similarity index 99% rename from docs/introduction/releases.rst rename to docs/community/releases.rst index db98f7d95..df87ca9bf 100644 --- a/docs/introduction/releases.rst +++ b/docs/community/releases.rst @@ -1,188 +1,193 @@ .. This file is part of Invenio Copyright (C) 2015, 2016, 2017 CERN. Invenio 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 2 of the License, or (at your option) any later version. Invenio 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 Invenio; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. Releases ======== +.. todo:: + + Move to versioning scheme to maintainers guide. Keep list of + releases. + Release numbering scheme ------------------------ Invenio stable releases use the classical major.minor.patchlevel release version numbering scheme that is commonly used in the GNU/Linux world and elsewhere. Each release is labelled by:: major.minor.patchlevel release version number. For example, a release version 4.0.1 means:: 4 - 4th major version, i.e. the whole system has been already 4th times either fully rewritten or at least in its very essential components. The upgrade from one major version to another may be rather hard, may require new prerequisite technologies, full data dump, reload and reindexing, as well as other major configuration adapatations, possibly with an important manual intervention. 0 - 0th minor version, i.e. the first minor release of the 4th major rewrite. (Increments go usually 4.1, 4.2, ... 4.9, 4.10, 4.11, 4.12, ... until some important rewrite is done, e.g. the database philosophy dramatically changes, leading to a non-trivial upgrade, and then we have either higher 4.x in the series or directly 5.0.0.) The upgrade from one minor version to another may be laborious but is relatively painless, in that some table changes and data manipulations may be necessary but they are somewhat smaller in nature, easier to grasp, and possibly done by a fully automated script. 1 - 1st patch level release to 4.0 series, fixing bugs in 4.0.0 but not adding any substantially new functionality. That is, the only new functionality that is added is that of a bug fix nature. The upgrade from one patch level to another is usually very straightforward. (Packages often seem to break this last rule, e.g. Linux kernel adopting new important functionality (such as ReiserFS) within the stable 2.4.x branch. It can be easily seen that it is somewhat subjective to judge what is qualitatively more like a minor new functionality and what is more like a patch to the existing behaviour. We have tried to distinguish this with respect to whether the table structure and/or the technology change require small or large upgrade jobs and eventual manual efforts.) So, if we have a version 4.3.0, a bug fix would mean to release 4.3.1, some minor new functionality and upgrade would mean to release 4.4.0, some important database structure rewrite or an imaginary exchange of Python for Common Lisp would mean to release 5.0.0, etc. We follow `semantic versioning `_ and `PEP-0440 `_ release numbering practices. Invenio v3.x ------------ *Not released yet; however a developer preview is available on GitHub.* Invenio v3.0 will be released when the Invenio code base is fully split into a set of standalone independent Python packages. Invenio v2.x ------------ *Semi-stable codebase.* Invenio v2.x code base is our new code base architecture that uses Flask web development framework. The most important modules take fully profit from the new architecture (e.g. search, deposit), however some modules still rely on previous v1.x legacy code base (e.g. baskets). Therefore its production suitability depends on your use case. Released versions include: Invenio v2.1: * `v2.1.1 `_ - released 2015-09-01 * `v2.1.0 `_ - released 2015-06-16 Invenio v2.0: * `v2.0.6 `_ - released 2015-09-01 * `v2.0.5 `_ - released 2015-07-17 * `v2.0.4 `_ - released 2015-06-01 * `v2.0.3 `_ - released 2015-05-15 * `v2.0.2 `_ - released 2015-04-17 * `v2.0.1 `_ - released 2015-03-20 * `v2.0.0 `_ - released 2015-03-04 Invenio v1.x ------------ *Stable codebase.* Invenio v1.x code base is suitable for stable production. It uses legacy technology and custom web development framework. Released versions include: Invenio v1.2: * `v1.2.2 `_ - released 2016-11-25 * `v1.2.1 `_ - released 2015-05-21 * `v1.2.0 `_ - released 2015-03-03 Invenio v1.1: * `v1.1.7 `_ - released 2016-11-20 * `v1.1.6 `_ - released 2015-05-21 * `v1.1.5 `_ - released 2015-03-02 * `v1.1.4 `_ - released 2014-08-31 * `v1.1.3 `_ - released 2014-02-25 * `v1.1.2 `_ - released 2013-08-19 * `v1.1.1 `_ - released 2012-12-21 * `v1.1.0 `_ - released 2012-10-21 Invenio v1.0: * `v1.0.10 `_ - released 2016-11-09 * `v1.0.9 `_ - released 2015-05-21 * `v1.0.8 `_ - released 2015-03-02 * `v1.0.7 `_ - released 2014-08-31 * `v1.0.6 `_ - released 2014-01-31 * `v1.0.5 `_ - released 2013-08-19 * `v1.0.4 `_ - released 2012-12-21 * `v1.0.3 `_ - released 2012-12-19 * `v1.0.2 `_ - released 2012-10-19 * `v1.0.1 `_ - released 2012-06-28 * `v1.0.0 `_ - released 2012-02-29 * `v1.0.0-rc0 `_ - released 2010-12-21 Invenio v0.x ------------ *Old codebase.* Invenio v0.x code base was developed and used in production instances since 2002. The code base is interesting only for archaeological purposes. Released versions include: * `v0.99.9 `_ - released 2014-01-31 * `v0.99.8 `_ - released 2013-08-19 * `v0.99.7 `_ - released 2012-12-18 * `v0.99.6 `_ - released 2012-10-18 * `v0.99.5 `_ - released 2012-02-21 * `v0.99.4 `_ - released 2011-12-19 * `v0.99.3 `_ - released 2010-12-13 * `v0.99.2 `_ - released 2010-10-20 * `v0.99.1 `_ - released 2008-07-10 * `v0.99.0 `_ - released 2008-03-27 * `v0.92.1 `_ - released 2007-02-20 * `v0.92.0. `_ - released 2006-12-22 * `v0.90.1 `_ - released 2006-07-23 * `v0.90.0 `_ - released 2006-06-30 * `v0.7.1 `_ - released 2005-05-04 * `v0.7.0 `_ - released 2005-04-06 * `v0.5.0 `_ - released 2004-12-17 * `v0.3.3 `_ - released 2004-07-16 * `v0.3.2 `_ - released 2004-05-12 * `v0.3.1 `_ - released 2004-03-12 * `v0.3.0 `_ - released 2004-03-05 * `v0.1.2 `_ - released 2003-12-21 * `v0.1.1 `_ - released 2003-12-19 * `v0.1.0 `_ - released 2003-12-04 * `v0.0.9 `_ - released 2002-08-01 diff --git a/docs/community/style-guide.rst b/docs/community/style-guide.rst new file mode 100644 index 000000000..20140dba5 --- /dev/null +++ b/docs/community/style-guide.rst @@ -0,0 +1,2 @@ +Style guide +=========== diff --git a/docs/community/translation-guide.rst b/docs/community/translation-guide.rst new file mode 100644 index 000000000..3573b9552 --- /dev/null +++ b/docs/community/translation-guide.rst @@ -0,0 +1,2 @@ +Translation guide +================= diff --git a/docs/community/twitter.rst b/docs/community/twitter.rst deleted file mode 100644 index 73027b974..000000000 --- a/docs/community/twitter.rst +++ /dev/null @@ -1,29 +0,0 @@ -.. This file is part of Invenio - Copyright (C) 2015 CERN. - - Invenio 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 2 of the - License, or (at your option) any later version. - - Invenio 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 Invenio; if not, write to the Free Software Foundation, Inc., - 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. - -Twitter -======= - -The official Twitter account for Invenio software is used mostly for announcing -new releases and talks at conferences: - -- ``_ - -There are several Invenio developers actively using Twitter and tweeting about -(not only) Invenio related matters. You can follow the aggregation list: - -- ``_ diff --git a/docs/conf.py b/docs/conf.py index 492e5a362..218309646 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -1,350 +1,351 @@ # -*- coding: utf-8 -*- # # This file is part of Invenio. # Copyright (C) 2015, 2016 CERN. # # Invenio 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 2 of the # License, or (at your option) any later version. # # Invenio 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 Invenio; if not, write to the # Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, # MA 02111-1307, USA. # # In applying this license, CERN does not # waive the privileges and immunities granted to it by virtue of its status # as an Intergovernmental Organization or submit itself to any jurisdiction. from __future__ import print_function import os import sphinx.environment # -- General configuration ------------------------------------------------ # If your documentation needs a minimal Sphinx version, state it here. #needs_sphinx = '1.0' # Do not warn on external images. suppress_warnings = ['image.nonlocal_uri'] # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. extensions = [ 'sphinx.ext.autodoc', 'sphinx.ext.coverage', + 'sphinx.ext.doctest', 'sphinx.ext.graphviz', 'sphinx.ext.intersphinx', - 'sphinx.ext.doctest', 'sphinx.ext.intersphinx', + 'sphinx.ext.todo', 'sphinx.ext.viewcode', ] graphviz_output_format = 'svg' # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] # The suffix(es) of source filenames. # You can specify multiple suffix as a list of string: # source_suffix = ['.rst', '.md'] source_suffix = '.rst' # The encoding of source files. #source_encoding = 'utf-8-sig' # The master toctree document. master_doc = 'index' # General information about the project. project = u'Invenio' copyright = u'2015, CERN' author = u'CERN' # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the # built documents. # # The short X.Y version. # Get the version string. Cannot be done with import! g = {} with open(os.path.join('..', 'invenio', 'version.py'), 'rt') as fp: exec(fp.read(), g) version = g['__version__'] # The full version, including alpha/beta/rc tags. release = version # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. # # This is also used if you do content translation via gettext catalogs. # Usually you set "language" from the command line for these cases. language = None # There are two options for replacing |today|: either, you set today to some # non-false value, then it is used: #today = '' # Else, today_fmt is used as the format for a strftime call. #today_fmt = '%B %d, %Y' # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. exclude_patterns = [] # The reST default role (used for this markup: `text`) to use for all # documents. #default_role = None # If true, '()' will be appended to :func: etc. cross-reference text. #add_function_parentheses = True # If true, the current module name will be prepended to all description # unit titles (such as .. function::). #add_module_names = True # If true, sectionauthor and moduleauthor directives will be shown in the # output. They are ignored by default. #show_authors = False # The name of the Pygments (syntax highlighting) style to use. pygments_style = 'sphinx' # A list of ignored prefixes for module index sorting. #modindex_common_prefix = [] # If true, keep warnings as "system message" paragraphs in the built documents. #keep_warnings = False # If true, `todo` and `todoList` produce output, else they produce nothing. -todo_include_todos = False +todo_include_todos = True # -- Options for HTML output ---------------------------------------------- html_theme = 'alabaster' html_theme_options = { 'logo': 'logo-full.png', 'description': 'Invenio Digital Library Framework.', 'github_user': 'inveniosoftware', 'github_repo': 'invenio', 'github_button': False, 'github_banner': True, 'show_powered_by': False, 'extra_nav_links': { 'invenio@GitHub': 'https://github.com/inveniosoftware/invenio', 'invenio@PyPI': 'https://pypi.python.org/pypi/invenio/', } } # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the # documentation. #html_theme_options = {} # Add any paths that contain custom themes here, relative to this directory. #html_theme_path = [] # The name for this set of Sphinx documents. If None, it defaults to # " v documentation". #html_title = None # A shorter title for the navigation bar. Default is the same as html_title. #html_short_title = None # The name of an image file (relative to this directory) to place at the top # of the sidebar. #html_logo = None # The name of an image file (within the static path) to use as favicon of the # docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 # pixels large. #html_favicon = None # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". html_static_path = ['_static'] # Add any extra paths that contain custom files (such as robots.txt or # .htaccess) here, relative to this directory. These files are copied # directly to the root of the documentation. #html_extra_path = [] # If not '', a 'Last updated on:' timestamp is inserted at every page bottom, # using the given strftime format. #html_last_updated_fmt = '%b %d, %Y' # If true, SmartyPants will be used to convert quotes and dashes to # typographically correct entities. #html_use_smartypants = True # Custom sidebar templates, maps document names to template names. html_sidebars = { '**': [ 'about.html', 'navigation.html', 'relations.html', 'searchbox.html', 'donate.html', ] } # Additional templates that should be rendered to pages, maps page names to # template names. #html_additional_pages = {} # If false, no module index is generated. #html_domain_indices = True # If false, no index is generated. #html_use_index = True # If true, the index is split into individual pages for each letter. #html_split_index = False # If true, links to the reST sources are added to the pages. #html_show_sourcelink = True # If true, "Created using Sphinx" is shown in the HTML footer. Default is True. #html_show_sphinx = True # If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. #html_show_copyright = True # If true, an OpenSearch description file will be output, and all pages will # contain a tag referring to it. The value of this option must be the # base URL from which the finished HTML is served. #html_use_opensearch = '' # This is the file name suffix for HTML files (e.g. ".xhtml"). #html_file_suffix = None # Language to be used for generating the HTML full-text search index. # Sphinx supports the following languages: # 'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'it', 'ja' # 'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr' #html_search_language = 'en' # A dictionary with options for the search language support, empty by default. # Now only 'ja' uses this config value #html_search_options = {'type': 'default'} # The name of a javascript file (relative to the configuration directory) that # implements a search results scorer. If empty, the default will be used. #html_search_scorer = 'scorer.js' # Output file base name for HTML help builder. htmlhelp_basename = 'invenio_namedoc' # -- Options for LaTeX output --------------------------------------------- latex_elements = { # The paper size ('letterpaper' or 'a4paper'). #'papersize': 'letterpaper', # The font size ('10pt', '11pt' or '12pt'). #'pointsize': '10pt', # Additional stuff for the LaTeX preamble. #'preamble': '', # Latex figure (float) alignment #'figure_align': 'htbp', } # Grouping the document tree into LaTeX files. List of tuples # (source start file, target name, title, # author, documentclass [howto, manual, or own class]). latex_documents = [ (master_doc, 'invenio.tex', u'invenio Documentation', u'CERN', 'manual'), ] # The name of an image file (relative to this directory) to place at the top of # the title page. #latex_logo = None # For "manual" documents, if this is true, then toplevel headings are parts, # not chapters. #latex_use_parts = False # If true, show page references after internal links. #latex_show_pagerefs = False # If true, show URL addresses after external links. #latex_show_urls = False # Documents to append as an appendix to all manuals. #latex_appendices = [] # If false, no module index is generated. #latex_domain_indices = True # -- Options for manual page output --------------------------------------- # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). man_pages = [ (master_doc, 'invenio', u'invenio Documentation', [author], 1) ] # If true, show URL addresses after external links. #man_show_urls = False # -- Options for Texinfo output ------------------------------------------- # Grouping the document tree into Texinfo files. List of tuples # (source start file, target name, title, author, # dir menu entry, description, category) texinfo_documents = [ (master_doc, 'invenio', u'Invenio Documentation', author, 'invenio', 'Invenio Digital Library Framework.', 'Miscellaneous'), ] # Documents to append as an appendix to all manuals. #texinfo_appendices = [] # If false, no module index is generated. #texinfo_domain_indices = True # How to display URL addresses: 'footnote', 'no', or 'inline'. #texinfo_show_urls = 'footnote' # If true, do not generate a @detailmenu in the "Top" node's menu. #texinfo_no_detailmenu = False # Example configuration for intersphinx: refer to the Python standard library. intersphinx_mapping = { 'python': ('https://docs.python.org/2.7/', None), 'flaskregistry': ('https://flask-registry.readthedocs.io/en/latest/', None), 'werkzeug': ('http://werkzeug.pocoo.org/docs/', None), 'flask': ('http://flask.pocoo.org/docs/', None), 'flaskassets': ('https://flask-assets.readthedocs.io/en/latest/', None), 'flaskscript': ('https://flask-script.readthedocs.io/en/latest/', None), 'sqlalchemy': ('http://docs.sqlalchemy.org/en/latest/', None), 'jinja': ('http://jinja.pocoo.org/docs/', None), 'webassets': ('https://webassets.readthedocs.io/en/latest/', None), } # Autodoc configuraton. autoclass_content = 'both' diff --git a/docs/configuration/overlay.rst b/docs/configuration/overlay.rst deleted file mode 100644 index 87f0f18a4..000000000 --- a/docs/configuration/overlay.rst +++ /dev/null @@ -1,631 +0,0 @@ -.. This file is part of Invenio - Copyright (C) 2014, 2015 CERN. - - Invenio 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 2 of the - License, or (at your option) any later version. - - Invenio 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 Invenio; if not, write to the Free Software Foundation, Inc., - 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. - -.. _overlay: - -================================== - How to create an Invenio overlay -================================== - -.. admonition:: CAVEAT LECTOR - - The following overlay guide was written for Invenio v2.0 release series. It - is to be updated for Invenio v3.0.x - -.. admonition:: TODO - - The following items are still missing from this document, feel free to - contribute to it. - - - celery/redis/honcho/flower - - populate the data - - Thanks - - -What is an overlay -================== - -Invenio is a library that enable the creation of an digital library but it -has to be coupled with an overlay. The overlay will contain your configuration -options, your desired look and feel, the extra invenio modules you've developed -and are using. - - -Creating your first Invenio overlay -=================================== - -If you've already setup the Invenio developer's environement itself, it will -feel familiar. We are reproducing here the steps for Ubuntu LTS. Other -distributions may be found in the previous link. - - -The global setup ----------------- - -Some softwares and libraries are required to work on your overlay. It's mostly -Python, MySQL, Redis as well as XML, XSLT and graphical libraries. Node.js is -solely required for development purposes. - -.. code-block:: console - - $ python --version - Python 2.7.5+ - $ sudo apt-get update - $ sudo apt-get install build-essential git redis-server \ - libmysqlclient-dev libxml2-dev libxslt-dev \ - libjpeg-dev libfreetype6-dev libtiff-dev \ - libffi-dev libssl-dev \ - software-properties-common python-dev \ - virtualenvwrapper - $ sudo pip install -U virtualenvwrapper pip - $ source .bashrc - - # Install MySQL server, and keep the root password somewhere safe. - $ sudo apt-get install mysql-server - - # Install node.js - $ curl -sL https://deb.nodesource.com/setup_4.x | sudo bash - - $ sudo apt-get install nodejs - -The virtual environment ------------------------ - -Python development usually recommends to work within a ``virtualenv``, which -creates an isolated environment where the libraries required by one will not -intervene with the system ones or the ones of another system. We are using -``virtualenvwrapper`` but nothing prevents your from directly using -``virtualenv`` you are familiar with it. - -.. code-block:: console - - $ mkvirtualenv myoverlay - (myoverlay)$ # we are in your overlay environment now and - (myoverlay)$ # can leave it using the deactivate command. - (myoverlay)$ deactivate - $ # Now join it back, recreating it would fail. - $ workon myoverlay - (myoverlay)$ # That's all there is to know about it. - -The base of the overlay ------------------------ - -Let's dive in. - -.. code-block:: console - - $ workon myoverlay - (myoverlay)$ cdvirtualenv - (myoverlay)$ mkdir -p src/myoverlay - (myoverlay)$ cd src/myoverlay - (myoverlay)$ edit setup.py - -The ``setup.py`` file contains the definition of a python package. Having one -means you can rely on existing tools like ``pip`` to package, install, deploy -it later on. Here is its minimal content. - -.. code-block:: python - - from setuptools import setup - from setuptools import setup, find_packages - packages = find_packages() - - setup( - name="My Overlay", - version="0.1.dev0", - url="http://inveniosoftware.org/", - author="Invenio Software", - author_email="invenio@inveniosoftware.org", - description="My first overlay", - packages=packages, - install_requires=[ - "Invenio>=2" - ], - entry_points={ - "invenio.config": ["myoverlay = myoverlay.config"] - } - ) - -Now we can install it in editable mode (``-e``), meaning you don't have to -reinstall it after each change - -.. code-block:: console - - (myoverlay)$ pip install -e . - -This will fetch the latest Invenio version published on PyPI. As a developer, -you may instead want to use the development version of Invenio from GitHub. To -do so, create a file called ``requirements.txt`` with the following content: - -.. code-block:: text - - git+git://github.com/inveniosoftware/invenio@pu#egg=Invenio-dev - -e . - -and install using: - -.. code-block:: console - - (myoverlay)$ pip install -r requirements.txt - -Configuration -============= - -As you've seen above, we defined an entry_point for ``myoverlay.config``. It -points to a module that will contain our configuration. So create your -application. - -.. code-block:: text - - src/ - │ - ├ myoverlay/ - │ │ - │ ├ base/ - │ │ │ - │ │ └ __init__.py - │ │ - │ ├ __init__.py - │ └ config.py - │ - ├ requirements.txt - └ setup.py - -Put the required configuration into ``config.py``. - -.. code-block:: python - - CFG_SITE_LANGS = ["en"] - - CFG_SITE_NAME = "My Overlay" - CFG_SITE_NAME_INTL = { - "en": CFG_SITE_NAME - } - - PACKAGES = [ - "myoverlay.base", - # TODO list your packages here - "invenio_base", - ] - - try: - from myoverlay.instance_config import * - except ImportError: - pass - - -Sensitive configuration ------------------------ - -Other configuration elements like database username and password or the website -url should not be put here as this file is not specific to the installation and -may be put under a version control system such as Git or Subversion. - -The configuration can be handled via the `inveniomanage` command line interface -(or by editing the `invenio.cfg` file in the instance folder and reloading -the application). - -.. code-block:: console - - (myoverlay)$ inveniomanage config set create secret-key - # MySQL configuration - (myoverlay)$ inveniomanage config set CFG_DATABASE_NAME mysql-database - (myoverlay)$ inveniomanage config set CFG_DATABASE_USER mysql-user - # HOST configuration (for redirects, etc.) - (myoverlay)$ inveniomanage config set CFG_SITE_URL http://invenio.example.com - (myoverlay)$ inveniomanage config set CFG_SITE_SECURE_URL https://invenio.example.com - (myoverlay)$ inveniomanage config set DEBUG True - (myoverlay)$ inveniomanage config set ASSETS_DEBUG True - - -Database setup --------------- - -.. code-block:: console - - (invenio)$ inveniomanage database init --user=root --password=$MYSQL_ROOT --yes-i-know - ... - >>> Database has been installed. - (invenio)$ inveniomanage database create - ... - >>> Tables filled successfully. - - -Assets ------- - -Most of the JavaScript and CSS libraries used are not bundled with invenio -itself and needs to be downloaded via `bower `_. Bower is -configured using two files: - -- `.bowerrc`: tells where the assets are downloaded -- `bower.json`: lists the dependencies to be downloaded - -The ``bower.json`` can be automagically generated through the `inveniomanage` -command. However, we will have to tell `bower` the path we want the libraries -downloaded to. In most cases, it will be in the instance directory under the -`static/vendors` path. - -.. code-block:: console - - $ sudo su -c "npm install -g bower less clean-css requirejs uglify-js" - (myoverlay)$ cdvirtualenv var/invenio.base-instance - (myoverlay)$ echo '{"directory": "static/vendors"}' > .bowerrc - (myoverlay)$ inveniomanage bower > bower.json - (myoverlay)$ bower install - -For invenio to see the static files from the ``myoverlay.base`` module, it -needs to declare a Flask blueprint. Create the following file: -``myoverlay/base/views.py``. - -.. code-block:: python - - from flask import Blueprint - - blueprint = Blueprint( - "myoverlay", - __name__, - url_prefix="/", - template_folder="templates", # where your custom templates will go - static_folder="static" # where the assets go - ) - -The assets will now be collected into the instance static folder from your -overlay, invenio itself and every libraries it uses. - -.. code-block:: console - - (myoverlay)$ inveniomanage collect - -Running -======= - -.. code-block:: console - - (myoverlay)$ inveniomanage runserver - - - -Translations -============ - -Invenio comes with full internationalization and localization support -based on `Babel `_ library and `Flask-Babel -`_. All strings you want to -translate in your overlay have to be marked with ``_()``. - -When you have all strings properly marked, it is time to prepare -catalog that contains all these strings for tranlations to desired -languages. - - -Configuration -------------- - -First of all, you have to get into the source folder of your overlay and -create a configuration file for *Babel*. - -.. code-block:: ini - - [python: **.py] - encoding = utf-8 - - [jinja2: **/templates/**] - encoding = utf-8 - extensions = jinja2.ext.autoescape.jinja2.ext.with_ - - -Save it as ``babel.cfg`` next to your ``setup.py``. Before we run the -extraction tool we need to add section to configure translation directory -to ``setup.cfg``. - -.. code-block:: ini - - [compile_catalog] - directory = myoverlay/base/translations/ - - [extract_messages] - output-file = myoverlay/base/translations/myoverlay.pot - - [init_catalog] - input-file = myoverlay/base/translations/myoverlay.pot - output-dir = myoverlay/base/translations/ - - [update_catalog] - input-file = myoverlay/base/translations/myoverlay.pot - output-dir = myoverlay/base/translations/ - -Message Extraction ------------------- - -Then it’s time to run the Babel string extraction with given -configuration: - -.. code-block:: console - - (myoverlay)$ python setup.py extract_messages - - -Create Catalog for New Language -------------------------------- - -Once all translatable strings are extracted, one need to prepare catalogs -for new languages. Following example shows how to prepare new catalog for -French in PO (Portable Object) format. - - -.. code-block:: console - - (myoverlay)$ python setup.py init_catalog -l fr - - -Now edit the ``myoverlay/base/translations/fr/LC_MESSAGES/messages.po`` -file as needed. - - -Compiling Catalog ------------------ - -Next step is to prepare MO (Machine Object) files in the format which is -defined by the GNU `gettext `_ tools -and the GNU `translation project -`_. - -To compile the translations for use, pybabel integration with distutils -helps again: - -.. code-block:: console - - (myoverlay)$ python setup.py compile_catalog - -If you install Invenio in development mode you must compile catalog also -from the Invenio directory project. - -.. note:: - - You should tell git to ignore your compliled translation by running: - - .. code-block:: console - - $ echo \*.mo >> .gitignore - - -Updating Strings ----------------- - -It is pretty common that your strings in the code will change over the -time. Pybabel provides support for updating the translation catalog with -new strings or changing existing ones. What do you have to do? Create a -new ``myoverlay.pot`` like above and then let pybabel merge the changes: - -.. code-block:: console - - $ python setup.py update_catalog - - -Deployment -========== - -Deploying Invenio is almost a piece of cake using `Fabric -`_. The following step are inspired by the Flask -documentation: `Deploying with Fabric -`_ - -Prerequisites -------------- - -First, you need a server with remote access (SSH), where you've installed all -the python dependencies (e.g. ``build-essentials``, ``python-dev``, -``libmysqlclient-dev``, etc.). - -Install `fabric` locally, - -.. code-block:: console - - $ pip install fabric - -and create a boilerplate ``fabfile.py``: - -.. code-block:: python - - import json - - from fabric.api import * - from fabric.utils import error - from fabric.contrib.files import exists - - - env.user = 'invenio' # remote username - env.directory = '/home/invenio/www' # remote directory - env.hosts = ['yourserver'] # list of servers - - -Preparing the tarball ---------------------- - -Before deploying anything, we need to locally prepare the python package to be -installed. Thanks to our ``setup.py`` file, it's very simple. - -Beforehand, we have to generate the static assets into our static folder. By -doing so, it's not required to install anything related to node.js on your -server (no ``bower``, ``less``, ``uglifyjs``, etc.). - -.. code-block:: python - - @task - def pack(): - """Create a new source distribution as tarball.""" - with open(".bowerrc") as fp: - bower = json.load(fp) - - local("inveniomanage assets build --directory {directory}/gen" - .format(**bower)) - return local("python setup.py sdist --formats=gztar", capture=False) \ - .succeeded - -Try it: - -.. code-block:: console - - $ fab pack - ... - Done - $ ls dist/ - My-Overlay-0.1.dev0.tar.gz - -This is the package that will be installed on your server. - -Creating the virtual environement ---------------------------------- - -We love virtual environments. We recommend you to install each version into its -own virtual env enabling quick rollbacks. - -.. code-block:: python - - @task - def create_virtualenv(): - """Create the virtualenv.""" - package = local("python setup.py --fullname", capture=True).strip() - venv = "{0}/{1}".format(env.directory, package) - - with cd(env.directory): - if exists(package): - return error("This version {0} is already installed." - .format(package)) - - return run("virtualenv {0}".format(package)).succeeded - - -Installing the package ----------------------- - -We can now upload the local tarball into the virtualenv, and install everything -there. - -.. code-block:: python - - @task - def install(): - """Install package.""" - package = local("python setup.py --fullname", capture=True).strip() - venv = "{0}/{1}".format(env.directory, package) - - if not exists(venv): - return error("Meh? I need a virtualenv first.") - - # Upload the package and put it into our virtualenv. - put("dist/{0}.tar.gz".format(package), "/tmp/app.tgz") - run("mkdir -p {0}/src".format(venv)) - with cd("{0}/src".format(venv)): - run("tar xzf /tmp/app.tgz") - run("rm -rf /tmp/app.tgz") - - # Jump into the virtualenv and install stuff - with cd("{0}/src/{1}".format(venv, package)): - success = run("{0}/bin/python setup.py install".format(venv) - - if success: - # post install - run("{0}/bin/inveniomanage collect".format(venv)) - return success - -Combining all the three steps: - -.. code-block:: console - - $ fab pack virtualenv install - - -Configuration -------------- - -The setup doesn't have the ``invenio.cfg`` file that is generated via -``inveniomanage config``. You should do so manually. - - -Running the server ------------------- - -uWSGI is super simple and neat, all you need is two files. In the example -below, we've installed two versions of our overlay and a symbolic link is -pointing to the one we want to run. - -.. code-block:: console - - $ ls www/ - current -> My-Overlay-0.1 - My-Overlay-0.1.dev1 - My-Overlay-0.1.dev2 - My-Overlay-0.1 - wsgi.py - uwsgi.ini - -Let's create the ``wsgi.py`` file. - -.. code-block:: python - - from invenio_base.factory import create_wsgi_app - - application = create_wsgi_app() - -And the µWSGI configuration: - -.. code-block:: python - - [uwsgi] - http = 0.0.0.0:4000 - master = true - - processes = 4 - die-on-term = true - vaccum = true - - chdir = %d - virtualenv = %d/current/ - module = wsgi:application - touch-reload = %d/wsgi.py - -Let's run it. - -.. code-block:: console - - $ pip install uwsgi - - $ uwsgi --ini uwsgi.ini - # or in daemon mode - $ uwsgi -d uwsgi.log --ini uwsgi.ini - -If the new version causes troubles, going back to the old one is as fast as -changing the symbolic link and restarting the WSGI server. - -.. code-block:: console - - $ rm current - $ ln -s My-Overlay-0.1.dev1 current - $ touch wsgi.py - -Dealing with versions ---------------------- - -One good idea is to use symlink to point to your current virtualenv and run -your overlay from there. Doing that via Fabric is left as an exercise to the -reader. - -When installing a new version, copying the ``invenio.cfg`` file over is the -only requirements. Restarting the WSGI server is usually done by ``touch``-ing -the ``wsgi.py`` file. diff --git a/docs/deploymentguide/configuring.rst b/docs/deploymentguide/configuring.rst new file mode 100644 index 000000000..6e79ebdfd --- /dev/null +++ b/docs/deploymentguide/configuring.rst @@ -0,0 +1,2 @@ +Configuration +============= diff --git a/docs/deploymentguide/daemons.rst b/docs/deploymentguide/daemons.rst new file mode 100644 index 000000000..f1e29adfb --- /dev/null +++ b/docs/deploymentguide/daemons.rst @@ -0,0 +1,2 @@ +Daemonizing applications +======================== diff --git a/docs/deploymentguide/docker.rst b/docs/deploymentguide/docker.rst new file mode 100644 index 000000000..e5a95cf33 --- /dev/null +++ b/docs/deploymentguide/docker.rst @@ -0,0 +1,2 @@ +Deploying with Docker +===================== diff --git a/docs/deploymentguide/fabric.rst b/docs/deploymentguide/fabric.rst new file mode 100644 index 000000000..86428ee8f --- /dev/null +++ b/docs/deploymentguide/fabric.rst @@ -0,0 +1,2 @@ +Deploying with Fabric +===================== diff --git a/docs/deploymentguide/highavailability.rst b/docs/deploymentguide/highavailability.rst new file mode 100644 index 000000000..9374d53ce --- /dev/null +++ b/docs/deploymentguide/highavailability.rst @@ -0,0 +1,14 @@ +High Availability +================= + +Load balancing +-------------- + +DNS load balancing +------------------ + +Distributed job queue +--------------------- + +Geo-replication +--------------- diff --git a/docs/installation/installation-detailed.rst b/docs/deploymentguide/installation-detailed.rst similarity index 100% rename from docs/installation/installation-detailed.rst rename to docs/deploymentguide/installation-detailed.rst diff --git a/docs/deploymentguide/monitoring.rst b/docs/deploymentguide/monitoring.rst new file mode 100644 index 000000000..847bc8aca --- /dev/null +++ b/docs/deploymentguide/monitoring.rst @@ -0,0 +1,13 @@ +Monitoring +========== + +Error monitoring +---------------- + + +Availability monitoring +----------------------- + + +Resource monitoring +------------------- diff --git a/docs/deploymentguide/overview.rst b/docs/deploymentguide/overview.rst new file mode 100644 index 000000000..802d34147 --- /dev/null +++ b/docs/deploymentguide/overview.rst @@ -0,0 +1,2 @@ +Overview +======== diff --git a/docs/deploymentguide/services.rst b/docs/deploymentguide/services.rst new file mode 100644 index 000000000..c156ec4f5 --- /dev/null +++ b/docs/deploymentguide/services.rst @@ -0,0 +1,14 @@ +Services +======== + +PostgreSQL +---------- + +Elasticsearch +------------- + +RabbitMQ +-------- + +Redis +----- diff --git a/docs/developersguide/architecture.rst b/docs/developersguide/architecture.rst new file mode 100644 index 000000000..4e0140972 --- /dev/null +++ b/docs/developersguide/architecture.rst @@ -0,0 +1,1372 @@ +Overview of architecture +======================== + + +Invenio v3.x +------------ + +.. admonition:: CAVEAT LECTOR + + Invenio v3.0 alpha is a bleeding-edge developer preview version. + +Invenio v3.0 build on top of `Flask`_ web development framework, using `Jinja2`_ +template engine, `SQLAlchemy`_ Object Relational Mapper, `JSONSchema`_ data +model, `PostgreSQL`_ database for persistence, and `Elasticsearch`_ for +information retrieval. + +.. _Flask: http://flask.pocoo.org/ +.. _Jinja2: http://jinja.pocoo.org/docs/ +.. _SQLAlchemy: http://www.sqlalchemy.org/ +.. _JSONSchema: http://json-schema.org/ +.. _PostgreSQL: http://www.postgresql.org/ +.. _Elasticsearch: https://www.elastic.co/products/elasticsearch + +Invenio's architecture is modular. The code base is split into more than 50 +independent components that are `released independently on PyPI +`_. +This ensures strict separation of components that talk among themselves over API +and permits rapid development of independent components by independent teams. + +Invenio compontents, named *modules*, can be roughly split in three categories: + +1. **base modules** provide interfaces to the Flask ecosystem, the Database, and + other system tools and technologies that the Invenio ecosystem uses. Example: + ``Invenio-Celery`` that talks to the Celery worker system. + +2. **core feature modules** provide most common functionality that each digital + library instance is likely interested in using. Example: ``Invenio-Records`` + provide record object store. + +3. **additional feature modules** offer additional functionality suitable for + various particular use cases, such as the Integrated Library System, the + Multimedia Store, or the Data Repository. Example: ``Invenio-Circulation`` + offers circulation and holdings capabilities. + +Here is a basic bird-eye overview of available Invenio components and their +dependencies: (*work in progress*) + +.. graphviz:: + + digraph invenio3 { + size="20.0 20.0"; + ratio="compress"; + + // helper floors + node [shape=plaintext,style=invis]; + { + Floor9 -> Floor8 [style=invis]; + Floor8 -> Floor7 [style=invis]; + Floor7 -> Floor6 [style=invis]; + Floor6 -> Floor5 [style=invis]; + Floor5 -> Floor4 [style=invis]; + Floor4 -> Floor3 [style=invis]; + Floor3 -> Floor2 [style=invis]; + Floor2 -> Floor1 [style=invis]; + Floor1 -> Floor0 [style=invis]; + } + + // invenio tools family + node [shape=ellipse,style=dotted]; + Elasticsearch; + "JSON Schema"; + MySQL; + PostgreSQL; + FS; + Drive; + Dropbox; + S3; + " Celery "; + Flask; + + // invenio base plate family + node [shape=box,style=filled]; + Access; + Admin; + Assets; + Base; + Celery -> " Celery "; + Config; + DB -> MySQL; + DB -> PostgreSQL; + I18N; + JSONSchemas -> "JSON Schema"; + Logging; + REST; + Theme; + Upgrader -> DB; + + // invenio search family + node [shape=box,style=filled, color=green]; + "Records-UI" -> Records; + "Records-REST" -> Records; + "Records-REST" -> PIDStore; + Records -> DB; + "Search-UI" -> Search; + Search -> Records; + "Records-REST" -> Search; + PIDStore -> Records; + PIDStore -> DB; + node [shape=ellipse,style=filled,color=grey]; + "Search-UI" -> "Query-Parser" ; + "Search-UI" -> unAPI; + node [shape=ellipse,style=dotted,color=black]; + Search -> Elasticsearch; + + // invenio deposit family + node [shape=box,style=filled, color=red]; + "Deposit-UI" -> Deposit; + "Deposit-REST" -> Deposit; + Deposit -> Workflows; + Deposit -> Knowledge; + Deposit -> Sequencegenerator; + Workflows -> Records; + Workflows -> Documents; + + // invenio accounts family + node [shape=box,style=filled, color="0.5 0.5 1.0"]; + "Profiles-UI" -> Profiles; + "Profiles-REST" -> Profiles; + "Groups-UI" -> Groups; + "Groups-REST" -> Groups; + Profiles -> Access; + Profiles -> Accounts; + Accounts -> Access; + Groups -> Accounts; + + // invenio helpers family + node [shape=ellipse,style=filled,color=grey]; + Documents; + Cloudconnector; + Testing; + Utils; + Ext; + Webhooks; + Redirector; + + // invenio OAIS family + node [shape=box,style=filled,color=orange]; + "OAIS-Audit-Store" -> DB; + "OAIS-SIP-Store" -> DB; + "OAIS-AIP-Store" -> Cloudconnector; + "OAIS-DIP-Store" -> DB; + Archiver; + Deposit -> "OAIS-SIP-Store"; + Workflows -> "OAIS-SIP-Store"; + Records -> Archiver; + Documents -> Archiver; + Archiver -> "OAIS-AIP-Store"; + Records -> "OAIS-Audit-Store"; + + // invenio add-ons family + node [shape=box, style=filled, color=yellow]; + Alerts -> Records; + Annotations -> Records; + Annotations -> Profiles; + Classifier -> Records; + Client -> "Records-REST"; + Client -> "Groups-REST"; + Client -> "Profiles-REST"; + Client -> "Deposit-REST"; + Documents -> Cloudconnector; + Documents -> FS; + Cloudconnector -> Dropbox; + Cloudconnector -> Drive; + Cloudconnector -> S3; + Collections -> Records; + Comments -> Records; + Comments -> Profiles; + Communities -> Collections; + Communities -> Groups; + Communities -> Profiles; + Deposit -> Documents; + Deposit -> Records; + Deposit -> PIDStore; + Documents -> Records; + Formatter -> Records; + Formatter -> "OAIS-DIP-Store"; + Records -> JSONSchemas; + News -> Theme; + OAIHarvester -> DB; + OAIHarvester -> Workflows; + OAIHarvester -> Records; + OAuthClient -> Accounts; + OAuth2Server -> Accounts; + Pages -> Theme; + Previewer -> Records; + Previewer -> "Previewer-ISPY"; + Editor -> "Records-REST"; + Checker -> "Records-REST"; + Merger -> "Records-REST"; + Statistics; + Tags -> Records; + Tags -> Profiles; + + // invenio ILS family + node [shape=box, style=filled, color=purple]; + "Circulation-UI" -> Circulation; + "Circulation-REST" -> Circulation; + "Acquisition-UI" -> Acquisition; + "Acquisition-REST" -> Acquisition; + Client -> "Circulation-REST"; + Client -> "Acquisition-REST"; + Circulation -> Records; + Circulation -> Accounts; + Acquisition -> Records; + Acquisition -> Accounts; + + + // invenio end user + node [shape=plaintext, color=white]; + Users; + Users -> "Deposit-UI"; + Users -> "Search-UI"; + Users -> "Records-UI"; + Users -> "Circulation-UI"; + Users -> "Acquisition-UI"; + + // floor 0 + { + rank = same; + Floor0; + Elasticsearch; + MySQL; + PostgreSQL; + " Celery "; + "JSON Schema"; + Flask; + Drive; + Dropbox; + S3; + FS; + } + + // floor 1 + { + rank = same; + Floor1; + Access; + Admin; + Assets; + Base; + Celery; + Config; + DB; + I18N; + JSONSchemas; + Logging; + Theme; + REST; + Upgrader; + DB; + Testing; + Utils; + Ext; + Webhooks; + Redirector; + } + + // floor 8 + { + rank = same; + Floor8; + "Records-UI"; + "Records-REST"; + "Deposit-UI"; + "Deposit-REST"; + "Search-UI"; + "Profiles-UI"; + "Profiles-REST"; + "Groups-UI"; + "Groups-REST"; + "Circulation-UI"; + "Circulation-REST"; + "Acquisition-UI"; + "Acquisition-REST"; + } + // floor 9 + { + rank = same; + Floor9; + Client; + Users; + } + + } + +For further information, see :ref:`module_anatomy` and :ref:`module_list` +sections. + +Invenio v2.x +------------ + +Invenio v2.x was a transitional release series combining legacy code base +(Invenio v1.x) with new technology (Flask etc as used in Invenio v3.x). + +Invenio v1.x +------------ + +Invenio consists of several more or less independent modules with precisely +defined functionality. The general criterion for module names is to use the +"Bib" prefix to denote modules that work more with the bibliographic data, and +the "Web" prefix to denote modules that work more with the Web interface. (The +difference is of course blurred in some cases, as in the case of search engine +that has got a web interface but searches bibliographic data.) + +.. image:: /_static/modules-overview-diagram.jpeg + +Follows a brief description of what each module does. + +- BibCheck permits administrators and library cataloguers to automate various + kind of tests on the metadata to see whether the metadata comply with quality + standards. For example, that certain metadata fields are of a certain length, + that they have numeric content, that they must not be present when other field + exists, that their content is governed by an authority base depending on + values of other fields, etc. The module can report its findings or can even + automatically correct some kind of errors. + +- BibClassify allows automatic extraction of keywords from fulltext documents, + based on the frequency of specific terms, taken from a controlled vocabulary. + Controlled vocabularies can be expressed as simple text thesauri or as + structured, RDF-compliant, taxonomies, to allow a semantic classification. + +- BibConvert allows metadata conversion from any structured or semi-structured + proprietary format into any other format, typically the MARC XML that is + natively used in Invenio. Nevertheless the input and output formats are fully + configurable and have been tested on data importations from more than one + hundred data sources. The power of this utility lies in the fact that no + structural attributes of data source are presumed, but they are defined in an + extensive data source configuration. Inevitably, this leads to a high + complexity of the BibConvert configuration language. Most frequent + configurations are provided with the Invenio distribution, such as a sample + configuration from Qualified Dublin Core into the MARCXML. In general the + BibConvert configuration consists from the source data descriptions and target + data descriptions. The processor then analyzes and parses the input data and + creates the resulting data structure, similarly as the XSLT processor would + do. Typically the BibConvert is aimed at usage for input data that do not + dispose of an XML representation. The source data is required to be structured + or semi-structured, (i.e. not expressed in natural language that is a subject + of information extraction task) and its processing involves several steps + including record separation and field extraction upto transformation of source + field values and their formatting. + +- BibEdit permits one to edit the metadata via a Web interface. + +- BibFormat is in charge of formatting the bibliographic metadata in numerous + ways. This truly enables the separation of data content administration and + formatting layout. BibFormat can act in the background and format the records + when needed, or can preformat records for some often used outputs, such as the + brief format used when displaying search results. The BibFormat settings can + be administered either through a user-friendly web interface, or directly by + editing human-readable configuration files. + +- OAIHarvest represents the OAi-PMH compatible harvester allowing the repository + to gather metadata from fellow OAi-compliant repositories and the OAi-PMH + repository management. Repository is built directly on top of the database and + disposes of an OAi repository manager that allows to perform the + administrative tasks on the repository aside from the principal generic data + administration module. The database can be partially or completely open for + harvesting in the scope of the OAi-PMH protocol. In this case, all data is + provided in raw form, where the semantics of individual tags is indicated + uniquely by the MARC21 naming convention. This is particularly interesting for + institutes that are specialized in cross-archive and cross-disciplinary + services provision, as for example the ARC service provider. + +- BibIndex module takes care of the indexation of metadata, references and full + text files. Two kinds of indexes -- word and phrase index -- are being + maintained. The user can define several logical indexes (e.g. author index, + title index, etc.) and the correspondence of which physical MARC21 metadata + tag goes into which logical field index. An index consists of two parts: (i) a + forward index listing various words (or phrases) found in the given field, + with the set of record identifiers where the given word can be found; and (ii) + a reverse index listing record identifiers, with the set of words of the given + record that go to the forward index. Such a two-part indexing technique allows + one to rapidly update only those words that have changed in the input metadata + record. The indexes were designed with the aim to provide fast user-response + search times and are faster than native MySQL (full text) indexes. + +- BibMatch permits to filter input XML files against the database content, + attempting to match records via certain criteria, for example to avoid + doubly-inputted records. + +- BibRank permits to set up various ranking criteria that will be used later by + the search engine. For example, ranking by the word frequency, or by some + metadata tag value such as journal name by means of the journal impact factor + knowledge base, or even by the number of downloads of a particular paper. Note + that BibRank is independent of BibIndex. + +- BibSched The bibliographic task scheduler is central unit of the system that + allows all other modules to access the bibliographic database in a controlled + manner, preventing sharing violation threats and assuring the coherent + execution of the database update tasks. The module comes with an + administrative interface that allows to monitor the task queue including + various possibilities of a manual intervention, for example to re-schedule + queued tasks, change the task order, etc. + +- BibUpload allows to load the new bibliographic data into the database. To + effectuate this task the data must be a well-formed XML file that complies + with the current metadata tag selection schema. Usually, the properly + structured input files of BibUpload come from the BibConvert utility. + +- ElmSubmit is an email submission gateway that permits for automatic document + uploads from trusted sources via email. (Usually web submission or harvesting + is preferred.) + +- MiscUtil is a collection of miscellaneous utilities that other modules are + using, like the international messages, etc. + +- WebAccess module is responsible for granting access to users for performing + various actions within the system. A Role-Based Access Control (RBAC) + technique is used, where users belong to several groups according to their + role in the system. Each user group can be granted to perform certain actions + depending on possible one more action arguments. WebAccess is presently used + mainly for the administrative interface. There are basically two kinds of + actions: (i) configuration of administrative modules and (ii) running + administrative tasks. + +- WebAlert module allows the end user to be alerted whenever a new document + matching her personal criteria is inserted into the database. The criteria + correspond to a typical user query as if it would be done via the search + interface. For example, a user may want to get notified whenever a new + document containing certain words, or of a certain subject, is inserted. A + user may create several alerts with a daily, weekly, or a monthly frequency. + The results of alert searches are either sent back to the user by email or can + also be stored into her baskets. + +- WebBasket module enables the end user of the system to store the documents she + is interested in in a personal basket or a personal shelf. The concept is + similar to popular shopping carts. One user may own several baskets. A basket + can be either private or public, allowing a simple document sharing mechanism + within a group. + +- WebComment provides a community-oriented tool to rank documents by the readers + or to share comments on the documents by the readers. Integrated with the + group-aware WebBasket, WebGroup, WebMessage tools, WebComment is at the heart + of the social network features of the Invenio software. + +- WebHelp presents some global user-level, admin-level, and hacker-level + documenation on Invenio. The module-specific documentation is included within + each particular module. + +- WebMessage permits the communication between (possibly anonymous) end users + via web message boards, to invite readers to join the groups, etc. + +- WebSearch module handles user requests to search for a certain words or + phrases in the database. Two types of searching can be performed: a word + search or a phrase search. The system allows for complex boolean queries, + regular expression searching, or a combined metadata, references and full text + file searching in one go. Users have a possibility to browse for present index + terms. If no direct match could have been found with the user-typed query + pattern, the system proposes alternative matches as a search guidance. The + search indexes were designed to provide fast response times for middle-sized + data collections of up to 106 records. The metadata corpus is organized into + metadata collections that are directly accessible through the browse function, + similarly to the popular concept of Web Directories. Orthogonal views on the + document corpus are enabled in the search interface via a concept of virtual + collections: for example, a document may be classified both according to its + type (e.g. preprint, book) and according to its Dewey decimal classification + number. Such a flexible organization views allows for the creation of easy + navigation schemata to the end users. + +- WebSession is a session and user management module that permits to + differentiate between users. Useful for personalization of the interface and + services like personal baskets and alerts. + +- WebStat is a configurable system that permits to gather statistics about the + health of the server, the usage of the system, as well as about some + particular system features. + +- WebStyle is a library of design-related modules that defines look and feel of + Invenio pages. + +- WebSubmit is a comprehensive submission system allowing authorized individuals + (authors, secretaries and repository maintenance staff) to submit individual + documents into the system. The submission system disposes of a flow-control + mechanism that assures the data approval by authorized units. In total there + are several different exploitable submission schemas at a disposal, including + an automated full text document conversion from various textual and image + formats. This module also disposes of information extraction functionality, + focusing on bibliographic entities such as references, authors, keywords or + other implicit metadata. + + + + Base modules + ============ + + The **base modules** provide interfaces to the base technology modules + used by the Invenio package ecosystem. + + cookiecutter-invenio-module + +++++++++++++++++++++++++++ + + - source code: ``_ + - releases: ``_ + - known issues: ``_ + - documentation: ``_ + + generator-invenio-js-module + +++++++++++++++++++++++++++ + + - source code: ``_ + - releases: ``_ + - known issues: ``_ + - documentation: ``_ + + invenio-admin + +++++++++++++ + + Invenio module that adds administration panel to the system. + + - source code: ``_ + - releases: ``_ + - known issues: ``_ + - documentation: ``_ + + invenio-assets + ++++++++++++++ + + Media assets management for Invenio. + + - source code: ``_ + - releases: ``_ + - known issues: ``_ + - documentation: ``_ + + invenio-base + ++++++++++++ + + Base package for building the Invenio application. + + - source code: ``_ + - releases: ``_ + - known issues: ``_ + - documentation: ``_ + + invenio-celery + ++++++++++++++ + + Celery module for Invenio. + + - source code: ``_ + - releases: ``_ + - known issues: ``_ + - documentation: ``_ + + invenio-config + ++++++++++++++ + + Invenio configuration loader. + + - source code: ``_ + - releases: ``_ + - known issues: ``_ + - documentation: ``_ + + invenio-db + ++++++++++ + + Database management for Invenio. + + - source code: ``_ + - releases: ``_ + - known issues: ``_ + - documentation: ``_ + + invenio-formatter + +++++++++++++++++ + + Jinja utilities for Invenio. + + - source code: ``_ + - releases: ``_ + - known issues: ``_ + - documentation: ``_ + + invenio-i18n + ++++++++++++ + + Invenio internationalization module. + + - source code: ``_ + - releases: ``_ + - known issues: ``_ + - documentation: ``_ + + invenio-logging + +++++++++++++++ + + Module providing logging capabilities. + + - source code: ``_ + - releases: ``_ + - known issues: ``_ + - documentation: ``_ + + invenio-mail + ++++++++++++ + + Invenio mail module. + + - source code: ``_ + - releases: ``_ + - known issues: ``_ + - documentation: ``_ + + invenio-oauth2server + ++++++++++++++++++++ + + Invenio module that implements OAuth 2 server. + + - source code: ``_ + - releases: ``_ + - known issues: ``_ + - documentation: ``_ + + invenio-oauthclient + +++++++++++++++++++ + + Invenio module that provides OAuth web authorization support. + + - source code: ``_ + - releases: ``_ + - known issues: ``_ + - documentation: ``_ + + invenio-rest + ++++++++++++ + + REST API module for Invenio. + + - source code: ``_ + - releases: ``_ + - known issues: ``_ + - documentation: ``_ + + invenio-theme + +++++++++++++ + + Invenio standard theme. + + - source code: ``_ + - releases: ``_ + - known issues: ``_ + - documentation: ``_ + + invenio-upgrader + ++++++++++++++++ + + Upgrader engine for Invenio modules. + + - source code: ``_ + - releases: ``_ + - known issues: ``_ + - documentation: ``_ + + invenio-webhooks + ++++++++++++++++ + + Invenio module for processing webhook events. + + - source code: ``_ + - releases: ``_ + - known issues: ``_ + - documentation: ``_ + + Core feature modules + ==================== + + The **core feature modules** provide most common functionality that each digital + library instance is likely interested in using, such as record store, + search, deposit, or access control capabilities. + + invenio-access + ++++++++++++++ + + Invenio module for common role based access control. + + - source code: ``_ + - releases: ``_ + - known issues: ``_ + - documentation: ``_ + + invenio-accounts + ++++++++++++++++ + + Invenio user management and authentication. + + - source code: ``_ + - releases: ``_ + - known issues: ``_ + - documentation: ``_ + + invenio-collections + +++++++++++++++++++ + + Invenio module for organizing metadata into collections. + + - source code: ``_ + - releases: ``_ + - known issues: ``_ + - documentation: ``_ + + invenio-deposit + +++++++++++++++ + + Module for depositing record metadata and uploading files. + + - source code: ``_ + - releases: ``_ + - known issues: ``_ + - documentation: ``_ + + invenio-files-js + ++++++++++++++++ + + - source code: ``_ + - releases: ``_ + - known issues: ``_ + - documentation: ``_ + + invenio-files-rest + ++++++++++++++++++ + + Files download/upload REST API similar to S3 for Invenio. + + - source code: ``_ + - releases: ``_ + - known issues: ``_ + - documentation: ``_ + + invenio-indexer + +++++++++++++++ + + Indexer for Invenio. + + - source code: ``_ + - releases: ``_ + - known issues: ``_ + - documentation: ``_ + + invenio-jsonschemas + +++++++++++++++++++ + + Invenio module for building and serving JSONSchemas. + + - source code: ``_ + - releases: ``_ + - known issues: ``_ + - documentation: ``_ + + invenio-marc21 + ++++++++++++++ + + Invenio module with nice defaults for MARC21 overlay. + + - source code: ``_ + - releases: ``_ + - known issues: ``_ + - documentation: ``_ + + invenio-oaiserver + +++++++++++++++++ + + Invenio module that implements OAI-PMH server. + + - source code: ``_ + - releases: ``_ + - known issues: ``_ + - documentation: ``_ + + invenio-pidstore + ++++++++++++++++ + + Invenio module that stores and registers persistent identifiers. + + - source code: ``_ + - releases: ``_ + - known issues: ``_ + - documentation: ``_ + + invenio-previewer + +++++++++++++++++ + + Invenio module for previewing files. + + - source code: ``_ + - releases: ``_ + - known issues: ``_ + - documentation: ``_ + + invenio-query-parser + ++++++++++++++++++++ + + Search query parser supporting Invenio and SPIRES search syntax. + + - source code: ``_ + - releases: ``_ + - known issues: ``_ + - documentation: ``_ + + invenio-records + +++++++++++++++ + + Invenio-Records is a metadata storage module. + + - source code: ``_ + - releases: ``_ + - known issues: ``_ + - documentation: ``_ + + invenio-records-files + +++++++++++++++++++++ + + Invenio modules that integrates records and files. + + - source code: ``_ + - releases: ``_ + - known issues: ``_ + - documentation: ``_ + + invenio-records-js + ++++++++++++++++++ + + - source code: ``_ + - releases: ``_ + - known issues: ``_ + - documentation: ``_ + + invenio-records-rest + ++++++++++++++++++++ + + REST API for invenio-records module. + + - source code: ``_ + - releases: ``_ + - known issues: ``_ + - documentation: ``_ + + invenio-records-ui + ++++++++++++++++++ + + User interface for Invenio-Records. + + - source code: ``_ + - releases: ``_ + - known issues: ``_ + - documentation: ``_ + + invenio-search + ++++++++++++++ + + Invenio module for information retrieval. + + - source code: ``_ + - releases: ``_ + - known issues: ``_ + - documentation: ``_ + + invenio-search-js + +++++++++++++++++ + + - source code: ``_ + - releases: ``_ + - known issues: ``_ + - documentation: ``_ + + invenio-search-ui + +++++++++++++++++ + + UI for Invenio-Search. + + - source code: ``_ + - releases: ``_ + - known issues: ``_ + - documentation: ``_ + + invenio-userprofiles + ++++++++++++++++++++ + + Invenio module that adds userprofiles to the platform. + + - source code: ``_ + - releases: ``_ + - known issues: ``_ + - documentation: ``_ + + Additional feature modules + ========================== + + The **additional feature modules** offer additional functionality suitable for + various particular use cases, such as the Integrated Library System, the + Multimedia Store, or the Data Repository. + + invenio-acquisitions + ++++++++++++++++++++ + + - source code: ``_ + - releases: ``_ + - known issues: ``_ + - documentation: ``_ + + invenio-annotations + +++++++++++++++++++ + + - source code: ``_ + - releases: ``_ + - known issues: ``_ + - documentation: ``_ + + invenio-authorities + +++++++++++++++++++ + + - source code: ``_ + - releases: ``_ + - known issues: ``_ + - documentation: ``_ + + invenio-circulation + +++++++++++++++++++ + + Invenio module for the circulation of bibliographic items. + + - source code: ``_ + - releases: ``_ + - known issues: ``_ + - documentation: ``_ + + invenio-client + ++++++++++++++ + + Command line client for Invenio. + + - source code: ``_ + - releases: ``_ + - known issues: ``_ + - documentation: ``_ + + invenio-comments + ++++++++++++++++ + + Invenio module that adds record commenting feature. + + - source code: ``_ + - releases: ``_ + - known issues: ``_ + - documentation: ``_ + + invenio-communities + +++++++++++++++++++ + + Invenio module that adds support for communities. + + - source code: ``_ + - releases: ``_ + - known issues: ``_ + - documentation: ``_ + + invenio-csl-js + ++++++++++++++ + + - source code: ``_ + - releases: ``_ + - known issues: ``_ + - documentation: ``_ + + invenio-csl-rest + ++++++++++++++++ + + REST API for Citation Style Language styles. + + - source code: ``_ + - releases: ``_ + - known issues: ``_ + - documentation: ``_ + + invenio-github + ++++++++++++++ + + Invenio module that adds GitHub integration to the platform. + + - source code: ``_ + - releases: ``_ + - known issues: ``_ + - documentation: ``_ + + invenio-groups + ++++++++++++++ + + Invenio module that adds support for user groups. + + - source code: ``_ + - releases: ``_ + - known issues: ``_ + - documentation: ``_ + + invenio-ill + +++++++++++ + + - source code: ``_ + - releases: ``_ + - known issues: ``_ + - documentation: ``_ + + invenio-memento + +++++++++++++++ + + Invenio module makes your site Memento compliant. + + - source code: ``_ + - releases: ``_ + - known issues: ``_ + - documentation: ``_ + + invenio-metrics + +++++++++++++++ + + Invenio module for collecting and publishing metrics. + + - source code: ``_ + - releases: ``_ + - known issues: ``_ + - documentation: ``_ + + invenio-migrator + ++++++++++++++++ + + Utilities for migrating past Invenio versions to Invenio 3.0. + + - source code: ``_ + - releases: ``_ + - known issues: ``_ + - documentation: ``_ + + invenio-oaiharvester + ++++++++++++++++++++ + + Invenio module for OAI-PMH metadata harvesting between repositories. + + - source code: ``_ + - releases: ``_ + - known issues: ``_ + - documentation: ``_ + + invenio-openaire + ++++++++++++++++ + + OpenAIRE service integration for Invenio repositories. + + - source code: ``_ + - releases: ``_ + - known issues: ``_ + - documentation: ``_ + + invenio-opendefinition + ++++++++++++++++++++++ + + Invenio module integrating Invenio repositories and OpenDefinition. + + - source code: ``_ + - releases: ``_ + - known issues: ``_ + - documentation: ``_ + + invenio-orcid + +++++++++++++ + + ORCID integration for Invenio. + + - source code: ``_ + - releases: ``_ + - known issues: ``_ + - documentation: ``_ + + invenio-pages + +++++++++++++ + + Static pages module for Invenio. + + - source code: ``_ + - releases: ``_ + - known issues: ``_ + - documentation: ``_ + + invenio-previewer-ispy + ++++++++++++++++++++++ + + Invenio previewer for ISPY visualisations. + + - source code: ``_ + - releases: ``_ + - known issues: ``_ + - documentation: ``_ + + invenio-sequencegenerator + +++++++++++++++++++++++++ + + Invenio module for generating sequences. + + - source code: ``_ + - releases: ``_ + - known issues: ``_ + - documentation: ``_ + + invenio-sipstore + ++++++++++++++++ + + Submission Information Package store for Invenio. + + - source code: ``_ + - releases: ``_ + - known issues: ``_ + - documentation: ``_ + + invenio-tags + ++++++++++++ + + Invenio module for record tagging by authenticated users. + + - source code: ``_ + - releases: ``_ + - known issues: ``_ + - documentation: ``_ + + invenio-xrootd + ++++++++++++++ + + XRootD file storage support for Invenio. + + - source code: ``_ + - releases: ``_ + - known issues: ``_ + - documentation: ``_ + + Standalone utilities + ==================== + + The **standalone utilities** developed for use in the Invenio ecysystem. + + cernservicexml + ++++++++++++++ + + Small library to generate a CERN XSLS Service XML. + + - source code: ``_ + - releases: ``_ + - known issues: ``_ + - documentation: ``_ + + citeproc-py-styles + ++++++++++++++++++ + + CSL styles. + + - source code: ``_ + - releases: ``_ + - known issues: ``_ + - documentation: ``_ + + datacite + ++++++++ + + Python API wrapper for the DataCite Metadata Store API. + + - source code: ``_ + - releases: ``_ + - known issues: ``_ + - documentation: ``_ + + dcxml + +++++ + + Dublin Core XML generation from Python dictionaries. + + - source code: ``_ + - releases: ``_ + - known issues: ``_ + - documentation: ``_ + + dictdiffer + ++++++++++ + + Dictdiffer is a library that helps you to diff and patch dictionaries. + + - source code: ``_ + - releases: ``_ + - known issues: ``_ + - documentation: ``_ + + dojson + ++++++ + + DoJSON is a simple Pythonic JSON to JSON converter. + + - source code: ``_ + - releases: ``_ + - known issues: ``_ + - documentation: ``_ + + domapping + +++++++++ + + DoMapping generates Elasticsearch mappings from JSON Schemas. + + - source code: ``_ + - releases: ``_ + - known issues: ``_ + - documentation: ``_ + + doschema + ++++++++ + + JSON Schema utility functions and commands. + + - source code: ``_ + - releases: ``_ + - known issues: ``_ + - documentation: ``_ + + flask-breadcrumbs + +++++++++++++++++ + + Flask-Breadcrumbs adds support for generating site breadcrumb navigation. + + - source code: ``_ + - releases: ``_ + - known issues: ``_ + - documentation: ``_ + + flask-celeryext + +++++++++++++++ + + Flask-CeleryExt is a simple integration layer between Celery and Flask. + + - source code: ``_ + - releases: ``_ + - known issues: ``_ + - documentation: ``_ + + flask-cli + +++++++++ + + Backport of Flask 1.0 new click integration. + + - source code: ``_ + - releases: ``_ + - known issues: ``_ + - documentation: ``_ + + flask-iiif + ++++++++++ + + Flask-IIIF extension provides easy IIIF API standard integration. + + - source code: ``_ + - releases: ``_ + - known issues: ``_ + - documentation: ``_ + + flask-menu + ++++++++++ + + Flask-Menu is a Flask extension that adds support for generating menus. + + - source code: ``_ + - releases: ``_ + - known issues: ``_ + - documentation: ``_ + + flask-notifications + +++++++++++++++++++ + + - source code: ``_ + - releases: ``_ + - known issues: ``_ + - documentation: ``_ + + flask-sitemap + +++++++++++++ + + - source code: ``_ + - releases: ``_ + - known issues: ``_ + - documentation: ``_ + + flask-sso + +++++++++ + + Flask-SSO extension that eases Shibboleth authentication. + + - source code: ``_ + - releases: ``_ + - known issues: ``_ + - documentation: ``_ + + idutils + +++++++ + + Small library for persistent identifiers used in scholarly communication. + + - source code: ``_ + - releases: ``_ + - known issues: ``_ + - documentation: ``_ + + intbitset + +++++++++ + + C-based extension implementing fast integer bit sets. + + - source code: ``_ + - releases: ``_ + - known issues: ``_ + - documentation: ``_ + + jsonresolver + ++++++++++++ + + JSON data resolver with support for plugins. + + - source code: ``_ + - releases: ``_ + - known issues: ``_ + - documentation: ``_ + + kwalitee + ++++++++ + + Kwalitee is a tool that runs static analysis checks on Git repository. + + - source code: ``_ + - releases: ``_ + - known issues: ``_ + - documentation: ``_ + + requirements-builder + ++++++++++++++++++++ + + Build requirements files from setup.py requirements. + + - source code: ``_ + - releases: ``_ + - known issues: ``_ + - documentation: ``_ + + workflow + ++++++++ + + Simple workflows for Python + + - source code: ``_ + - releases: ``_ + - known issues: ``_ + - documentation: ``_ + + xrootdpyfs + ++++++++++ + + XRootDPyFS is a PyFilesystem interface to XRootD. + + - source code: ``_ + - releases: ``_ + - known issues: ``_ + - documentation: ``_ diff --git a/docs/developersguide/create-a-datamodel.rst b/docs/developersguide/create-a-datamodel.rst new file mode 100644 index 000000000..fcd512473 --- /dev/null +++ b/docs/developersguide/create-a-datamodel.rst @@ -0,0 +1,2 @@ +Creating a data model +===================== diff --git a/docs/developersguide/development-environment.rst b/docs/developersguide/development-environment.rst new file mode 100644 index 000000000..e1ab20b68 --- /dev/null +++ b/docs/developersguide/development-environment.rst @@ -0,0 +1,2 @@ +Setting up your development environment +======================================= diff --git a/docs/technology/docker.rst b/docs/developersguide/docker.rst similarity index 100% rename from docs/technology/docker.rst rename to docs/developersguide/docker.rst diff --git a/docs/technology/git.rst b/docs/developersguide/git.rst similarity index 100% rename from docs/technology/git.rst rename to docs/developersguide/git.rst diff --git a/docs/architecture/module-anatomy-structure.rst b/docs/developersguide/invenio-modules.rst similarity index 66% rename from docs/architecture/module-anatomy-structure.rst rename to docs/developersguide/invenio-modules.rst index 957126741..4b447acf0 100644 --- a/docs/architecture/module-anatomy-structure.rst +++ b/docs/developersguide/invenio-modules.rst @@ -1,82 +1,84 @@ -.. This file is part of Invenio - Copyright (C) 2014 CERN. - - Invenio 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 2 of the - License, or (at your option) any later version. - - Invenio 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 Invenio; if not, write to the Free Software Foundation, Inc., - 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. - -Module structure -================ +Invenio module layout +===================== This page summarizes the standard structure and naming conventions of a module in Invenio v2.0.0. It serves as a reference point when developing a new module, enhancing an existing one or porting a module from older versions of Invenio. The previous pages explained briefly what a module usually consists of, here we will go deeper into what goes where inside the module. A simple module may have the following folder structure:: invenio/modules/ mymodule/ __init__.py api.py models.py config.py views.py These files are: ``___init__.py`` (usually) an empty file that tells Python that this directory should be considered a Python package. Module level documentation are sometimes located here. ``models.py`` contains the data model for the modules (written as SQLAlchemy models). See how (link here) ``config.py`` contains module-wide configuration with prefix ``MYMODULE_*``. See how to import (link here) ``views.py`` contains Flask blueprints if the module requires a web-interface. Multiple views? (link here) ``api.py`` contains the API for other modules to access features of this module. Additional files: ``signals.py`` define custom signals here. See signals module. ``receivers.py`` define your custom signal receivers here. See signals module. ``errors.py`` contains any custom module-specific exceptions. For example:: class MyException(Exception): pass ``user_settings.py`` TODO ``forms.py`` TODO ``tasks.py`` TODO ``restful.py`` TODO + +Module naming conventions +------------------------- + +Invenio modules are standalone independent components that implement some +functionality used by the rest of the Invenio ecosystem. The modules provide API +to other modules and use API of other modules. + +A module is usually called: + +1. with plural noun, meaning "database (of things)", for example + ``invenio-records``, ``invenio-tags``, ``invenio-annotations``, + +2. with singular noun, meaning "worker (using things)", for example + ``invenio-checker``, ``invenio-editor``. + +A module may have split its user interface and REST API interface, for example +``invenio-records-ui`` and ``invenio-records-rest``, to clarify dependencies and +offer easy customisation. diff --git a/docs/technology/python.rst b/docs/developersguide/python.rst similarity index 100% rename from docs/technology/python.rst rename to docs/developersguide/python.rst diff --git a/docs/developersguide/tutorial/cookiecutter.rst b/docs/developersguide/tutorial/cookiecutter.rst new file mode 100644 index 000000000..59d106b8d --- /dev/null +++ b/docs/developersguide/tutorial/cookiecutter.rst @@ -0,0 +1,2 @@ +Part 1: Bootstrapping with cookiecutter +======================================= diff --git a/docs/developersguide/tutorial/develop.rst b/docs/developersguide/tutorial/develop.rst new file mode 100644 index 000000000..7912741d4 --- /dev/null +++ b/docs/developersguide/tutorial/develop.rst @@ -0,0 +1,2 @@ +Part 3: Develop a module +======================== diff --git a/docs/developersguide/tutorial/github-travis-pypi.rst b/docs/developersguide/tutorial/github-travis-pypi.rst new file mode 100644 index 000000000..bfb0e3ef1 --- /dev/null +++ b/docs/developersguide/tutorial/github-travis-pypi.rst @@ -0,0 +1,2 @@ +Part 5: Publish to GitHub, Travis and PyPI +========================================== diff --git a/docs/developersguide/tutorial/index.rst b/docs/developersguide/tutorial/index.rst new file mode 100644 index 000000000..6144d9a6d --- /dev/null +++ b/docs/developersguide/tutorial/index.rst @@ -0,0 +1,11 @@ +First steps +=========== + +.. toctree:: + :maxdepth: 2 + + cookiecutter + run-n-test + develop + submit-pr + github-travis-pypi diff --git a/docs/developersguide/tutorial/run-n-test.rst b/docs/developersguide/tutorial/run-n-test.rst new file mode 100644 index 000000000..58764dcbe --- /dev/null +++ b/docs/developersguide/tutorial/run-n-test.rst @@ -0,0 +1,6 @@ +Part 2: Install, run and test +============================= + +pip install -e .[all] +./run-tests.sh +python setup.py build_sphinx diff --git a/docs/developersguide/tutorial/submit-pr.rst b/docs/developersguide/tutorial/submit-pr.rst new file mode 100644 index 000000000..40b16b3e5 --- /dev/null +++ b/docs/developersguide/tutorial/submit-pr.rst @@ -0,0 +1,2 @@ +Part 4: Submit a pull-request +============================= diff --git a/docs/index.rst b/docs/index.rst index 394a217cd..b2a3799ee 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,43 +1,101 @@ .. This file is part of Invenio. Copyright (C) 2014, 2015 CERN. Invenio 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 2 of the License, or (at your option) any later version. Invenio 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 Invenio; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. In applying this license, CERN does not waive the privileges and immunities granted to it by virtue of its status as an Intergovernmental Organization or submit itself to any jurisdiction. .. include:: ../README.rst -========= - Invenio -========= +Overview +-------- .. toctree:: - :numbered: - :maxdepth: 2 - - introduction/index - installation/index - configuration/index - architecture/index - modules/index - technology/index - processes/index - community/index - authors - license + :maxdepth: 2 + + introduction/index + introduction/digitalrepositories + introduction/usecases + introduction/history + +User's Guide +------------ +This part of the documentation will show you how to get started using Invenio. + +.. toctree:: + :maxdepth: 2 + + usersguide/tutorial/index + usersguide/running + usersguide/loading + usersguide/accessing + usersguide/orcid-login + usersguide/migrating + +Deployment Guide +---------------- +This part of the documentation will show you how to setup a production system +for running Invenio. + +.. toctree:: + :maxdepth: 2 + + deploymentguide/overview + deploymentguide/services + deploymentguide/configuring + deploymentguide/daemons + deploymentguide/monitoring + deploymentguide/highavailability + deploymentguide/fabric + deploymentguide/docker + + +Developer's Guide +----------------- +This part of the documentation will show you how to get started developing for +Inveno. + +.. toctree:: + :maxdepth: 2 + + developersguide/tutorial/index + developersguide/development-environment + developersguide/architecture + developersguide/invenio-modules + developersguide/create-a-model + + +Community +--------- +Notes on getting involved, contributing, legal information and release notes +are here for the interested. + +.. toctree:: + :maxdepth: 2 + + community/getting-involved + community/code-of-conduct + community/translation-guide + community/contribution-guide + community/style-guide + community/maintainers-guide/index.rst + community/releases + community/license + community/authors + todo diff --git a/docs/installation/index.rst b/docs/installation/index.rst deleted file mode 100644 index 01a9ac50e..000000000 --- a/docs/installation/index.rst +++ /dev/null @@ -1,27 +0,0 @@ -.. This file is part of Invenio - Copyright (C) 2015 CERN. - - Invenio 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 2 of the - License, or (at your option) any later version. - - Invenio 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 Invenio; if not, write to the Free Software Foundation, Inc., - 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. - -============ -Installation -============ - -.. toctree:: - :maxdepth: 2 - - installation-quick - installation-detailed - upgrades diff --git a/docs/installation/upgrades.rst b/docs/installation/upgrades.rst deleted file mode 100644 index 683fd2e74..000000000 --- a/docs/installation/upgrades.rst +++ /dev/null @@ -1,48 +0,0 @@ -.. This file is part of Invenio - Copyright (C) 2014, 2015 CERN. - - Invenio 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 2 of the - License, or (at your option) any later version. - - Invenio 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 Invenio; if not, write to the Free Software Foundation, Inc., - 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. - -======== -Upgrades -======== - -Invenio community is working hard on new features and fixing bugs that -were found after release. While the upgrade can be a complex process at -times, running the latest Invenio version has several benefits: - -- Bugs are fixed. - -- New features and improvements are added. - -- Upgrading soon after a new Invenio release is available makes all future - upgrades less painful by keeping your code base always up to date. - -The upgrades are fully automatised so that it is usually sufficient to do:: - - inveniomanage upgrader show pending - inveniomanage upgrader check - inveniomanage upgrader run - -This will show the upgrade recipes which are to be run, check whether everything -is alright, and perform the upgrade operations themselves. Note that the upgrade -recipes may warn you about any further action that are necessary to execute -manually. - -Please refer to the `invenio-upgrader -`_ module documentation for more -details. - - diff --git a/docs/introduction/demo.rst b/docs/introduction/demo.rst deleted file mode 100644 index aa5699d20..000000000 --- a/docs/introduction/demo.rst +++ /dev/null @@ -1,73 +0,0 @@ -.. This file is part of Invenio - Copyright (C) 2014 CERN. - - Invenio 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 2 of the - License, or (at your option) any later version. - - Invenio 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 Invenio; if not, write to the Free Software Foundation, Inc., - 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. - -Demo -==== - -There are several Invenio installations that you can have a look at in -order to see it in action: - -Demo Sites ----------- - -`Atlantis Institute of Fictive Science `_ - *running Invenio 1.2.1, released 2015-05-21* - - Atlantis Institute of Fictive Science is an official demo site of - Invenio. It demonstrates a basic setup of Invenio. You could - (should) obtain this site if you install Invenio for the first - time, by lauching ``inveniocfg --create-demo-site`` and - ``inveniocfg --load-demo-records``. This is useful to verify the - functionality of your installation prior to customizing the system - for production. - -Production Sites ----------------- - -.. image:: /_static/CDS20120611.png - :width: 200 px - :align: right - -`CERN Document Server `_ - *CERN, Geneva, Switzerland* - - At CERN, Invenio manages over 800,000 bibliographic records and - 350,000 fulltext documents, organized in more than 500 - collections, covering preprints, articles, books, journals, - photographs, videos and more, of interest to people working in - particle physics. You can check out this site if you want to see - the performance and scalability of Invenio. - - -.. image:: /_static/Inspire20120611.png - :width: 200 px - :align: right - -`INSPIRE `_ - *CERN, Geneva, Switzerland* - - INSPIRE is the high-energy physics information system that combines the - successful `SPIRES `_ database - content, curated at `DESY `_, `Fermilab - `_ and `SLAC `_ - for decades, with the Invenio digital library technology developed at - `CERN `_. INSPIRE is run by a collaboration of the - four labs and interacts closely with high-energy physics publishers, - `arXiv.org `_, `NASA-ADS `_, - `PDG `_, and other information resources. - -[...] diff --git a/docs/introduction/about.rst b/docs/introduction/digitalrepositories.rst similarity index 70% rename from docs/introduction/about.rst rename to docs/introduction/digitalrepositories.rst index 99ca19c71..fbe154c00 100644 --- a/docs/introduction/about.rst +++ b/docs/introduction/digitalrepositories.rst @@ -1,24 +1,41 @@ .. This file is part of Invenio Copyright (C) 2014 CERN. Invenio 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 2 of the License, or (at your option) any later version. Invenio 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 Invenio; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. -About -===== +Digital repositories +==================== -.. include:: ../../README.rst - :start-after: pr-badge +.. todo:: + Write this section +What is a digital repository? +----------------------------- + +Record keeping +-------------- + +Persistent identifiers +---------------------- + +Metadata +-------- + +Data +---- + +Open Archival Information Systems (OAIS) +---------------------------------------- diff --git a/docs/introduction/features.rst b/docs/introduction/features.rst deleted file mode 100644 index 5daf08899..000000000 --- a/docs/introduction/features.rst +++ /dev/null @@ -1,94 +0,0 @@ -.. This file is part of Invenio - Copyright (C) 2014 CERN. - - Invenio 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 2 of the - License, or (at your option) any later version. - - Invenio 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 Invenio; if not, write to the Free Software Foundation, Inc., - 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. - -Features -======== - -Navigable collection tree -------------------------- - -.. image:: /_static/snap1.gif - :width: 200 px - :align: left - -* Documents organised in collections -* Regular and virtual collection trees -* Customizable portalboxes for each collection -* At CERN, over 1,000,000 documents in 700 collections - -.. raw:: html - -
- -Powerful search engine ----------------------- - -.. image:: /_static/snap2.gif - :width: 200 px - :align: left - -* Specially designed indexes to provide fast search speed for repositories of up to 2,000,000 records -* Customizable simple and advanced search interfaces -* Combined metadata, fulltext and citation search in one go -* Results clustering by collection - -.. raw:: html - -
- -Flexible metadata ------------------ - -.. image:: /_static/snap3.gif - :width: 200 px - :align: left - -* Standard metadata format (MARC) -* Handling articles, books, theses, photos, videos, museum objects and more -* Customizable display and linking rules - -.. raw:: html - -
- -User personalization --------------------- - -.. image:: /_static/snap4.gif - :width: 200 px - :align: left - -* user-defined document baskets -* user-defined automated email notification alerts -* basket-sharing within user groups -* Amazon-like user comments for documents in repository and shared baskets - -.. raw:: html - -
- -Multiple output formats ------------------------ - -.. image:: /_static/invenio_formats.jpg - :width: 200 px - :align: left - -.. raw:: html - -
- diff --git a/docs/introduction/history.rst b/docs/introduction/history.rst new file mode 100644 index 000000000..6c2b782cc --- /dev/null +++ b/docs/introduction/history.rst @@ -0,0 +1,59 @@ +History +======= + +Invenio v3 for v1 users +----------------------- +Invenio v3 is a completely new application that has been rewritten from scratch +in roughly a year. Why such a dramatic decision? To understand why the rewrite +was necessary we have to go back to when Invenio was called CDSWare, back to +August 1st 2002 when the first version of Invenio was released. + +In 2002: + +* First iPod had just hit the market (Nov 2001). +* The Budapest Open Access Initiative had just been signed (Feb, 2002). +* JSON had just been discovered (2001). +* Python 2.1 had just been released (2001). +* Apache Lucene had just joined the Apache Jakarta project (but not yet an + official top-level project). +* MySQL v4.0 beta was released and did not even have transactions yet. +* Hibernate ORM was released. +* The first DOI had just been assigned to a dataset. + +Following products did not even exists: + +* Apache Solr (2004) +* Google Maps (2005) +* Google Scholar (2004) +* Facebook (2007) +* Django (2005) + +A lot has happen in the past 15 years. Many problems that Invenio originally +had to deal with now have open source off-the-shelf solutions available. In +particular two things happen: + +* Search become pervasive with the exponential growth of data collected and + created on the internet every day, and open source products to solve handles + these needs like Elasticsearch became big business. +* Web frameworks for both front-end and back-end made it significant faster to + develop web applications. + +What happened to Invenio v2? +---------------------------- +Initial in 2011 we started out on creating a hybrid application which would +allow us to progressively migrate features as we had the time. In 2013 we +launched Zenodo as the first site on the v2 development version which among +other things featured Jinja templates instead of the previous Python based +templates. + +In theory everything was sound, however over the following years it became very +difficult to manage the inflow of changes from larger and larger teams on the +development side and operationally proved to be quite unstable compared to v1. + +Last but not least, Invenio v1 was built in a time where the primary need was +publication repositories and v2 inherited this legacy making it difficult to +deal with very large research datasets. + +Thus, in late 2015 we were being slowed so much down by our past legacy that we +saw no other way that starting over from scratch if we were to deal with the +next 20 years of challenges. diff --git a/docs/introduction/index.rst b/docs/introduction/index.rst index 6bde97f3d..fa7c57a92 100644 --- a/docs/introduction/index.rst +++ b/docs/introduction/index.rst @@ -1,30 +1,109 @@ .. This file is part of Invenio Copyright (C) 2015 CERN. Invenio 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 2 of the License, or (at your option) any later version. Invenio 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 Invenio; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. .. _introduction: -============ -Introduction -============ +What is Invenio? +================ -.. toctree:: - :maxdepth: 1 +.. todo:: - about - features - demo - releases + Fix up this section + +Features +-------- + +Navigable collection tree +~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. image:: /_static/snap1.gif + :width: 200 px + :align: left + +* Documents organised in collections +* Regular and virtual collection trees +* Customizable portalboxes for each collection +* At CERN, over 1,000,000 documents in 700 collections + +.. raw:: html + +
+ +Powerful search engine +~~~~~~~~~~~~~~~~~~~~~~ + +.. image:: /_static/snap2.gif + :width: 200 px + :align: left + +* Specially designed indexes to provide fast search speed for repositories of up to 2,000,000 records +* Customizable simple and advanced search interfaces +* Combined metadata, fulltext and citation search in one go +* Results clustering by collection + +.. raw:: html + +
+ +Flexible metadata +~~~~~~~~~~~~~~~~~ + +.. image:: /_static/snap3.gif + :width: 200 px + :align: left + +* Standard metadata format (MARC) +* Handling articles, books, theses, photos, videos, museum objects and more +* Customizable display and linking rules + +.. raw:: html + +
+ +User personalization +~~~~~~~~~~~~~~~~~~~~ + +.. image:: /_static/snap4.gif + :width: 200 px + :align: left + +* user-defined document baskets +* user-defined automated email notification alerts +* basket-sharing within user groups +* Amazon-like user comments for documents in repository and shared baskets + +.. raw:: html + +
+ +Multiple output formats +~~~~~~~~~~~~~~~~~~~~~~~ + +.. image:: /_static/invenio_formats.jpg + :width: 200 px + :align: left + +.. raw:: html + +
+ + +Who is using Invenio? +===================== +.. todo:: + + Write this section diff --git a/docs/introduction/usecases.rst b/docs/introduction/usecases.rst new file mode 100644 index 000000000..b0bddcabf --- /dev/null +++ b/docs/introduction/usecases.rst @@ -0,0 +1,21 @@ +Use cases +========= + +.. todo:: + + Write this section + +Integrated library system (ILS) +------------------------------- + + +Research data management (RDM) +------------------------------ + + +Institutional repository (IR) +----------------------------- + + +Multimedia archive +------------------ diff --git a/docs/modules/index.rst b/docs/modules/index.rst deleted file mode 100644 index 0518e45bf..000000000 --- a/docs/modules/index.rst +++ /dev/null @@ -1,27 +0,0 @@ -.. This file is part of Invenio - Copyright (C) 2015 CERN. - - Invenio 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 2 of the - License, or (at your option) any later version. - - Invenio 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 Invenio; if not, write to the Free Software Foundation, Inc., - 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. - -.. _module_list: - -======= -Modules -======= - -.. toctree:: - :maxdepth: 2 - - list diff --git a/docs/modules/list.rst b/docs/modules/list.rst deleted file mode 100644 index c0241c340..000000000 --- a/docs/modules/list.rst +++ /dev/null @@ -1,897 +0,0 @@ -.. This file is part of Invenio - Copyright (C) 2015, 2016 CERN. - - Invenio 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 2 of the - License, or (at your option) any later version. - - Invenio 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 Invenio; if not, write to the Free Software Foundation, Inc., - 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. - -Base modules -============ - -The **base modules** provide interfaces to the base technology modules -used by the Invenio package ecosystem. - -cookiecutter-invenio-module -+++++++++++++++++++++++++++ - -- source code: ``_ -- releases: ``_ -- known issues: ``_ -- documentation: ``_ - -generator-invenio-js-module -+++++++++++++++++++++++++++ - -- source code: ``_ -- releases: ``_ -- known issues: ``_ -- documentation: ``_ - -invenio-admin -+++++++++++++ - -Invenio module that adds administration panel to the system. - -- source code: ``_ -- releases: ``_ -- known issues: ``_ -- documentation: ``_ - -invenio-assets -++++++++++++++ - -Media assets management for Invenio. - -- source code: ``_ -- releases: ``_ -- known issues: ``_ -- documentation: ``_ - -invenio-base -++++++++++++ - -Base package for building the Invenio application. - -- source code: ``_ -- releases: ``_ -- known issues: ``_ -- documentation: ``_ - -invenio-celery -++++++++++++++ - -Celery module for Invenio. - -- source code: ``_ -- releases: ``_ -- known issues: ``_ -- documentation: ``_ - -invenio-config -++++++++++++++ - -Invenio configuration loader. - -- source code: ``_ -- releases: ``_ -- known issues: ``_ -- documentation: ``_ - -invenio-db -++++++++++ - -Database management for Invenio. - -- source code: ``_ -- releases: ``_ -- known issues: ``_ -- documentation: ``_ - -invenio-formatter -+++++++++++++++++ - -Jinja utilities for Invenio. - -- source code: ``_ -- releases: ``_ -- known issues: ``_ -- documentation: ``_ - -invenio-i18n -++++++++++++ - -Invenio internationalization module. - -- source code: ``_ -- releases: ``_ -- known issues: ``_ -- documentation: ``_ - -invenio-logging -+++++++++++++++ - -Module providing logging capabilities. - -- source code: ``_ -- releases: ``_ -- known issues: ``_ -- documentation: ``_ - -invenio-mail -++++++++++++ - -Invenio mail module. - -- source code: ``_ -- releases: ``_ -- known issues: ``_ -- documentation: ``_ - -invenio-oauth2server -++++++++++++++++++++ - -Invenio module that implements OAuth 2 server. - -- source code: ``_ -- releases: ``_ -- known issues: ``_ -- documentation: ``_ - -invenio-oauthclient -+++++++++++++++++++ - -Invenio module that provides OAuth web authorization support. - -- source code: ``_ -- releases: ``_ -- known issues: ``_ -- documentation: ``_ - -invenio-rest -++++++++++++ - -REST API module for Invenio. - -- source code: ``_ -- releases: ``_ -- known issues: ``_ -- documentation: ``_ - -invenio-theme -+++++++++++++ - -Invenio standard theme. - -- source code: ``_ -- releases: ``_ -- known issues: ``_ -- documentation: ``_ - -invenio-upgrader -++++++++++++++++ - -Upgrader engine for Invenio modules. - -- source code: ``_ -- releases: ``_ -- known issues: ``_ -- documentation: ``_ - -invenio-webhooks -++++++++++++++++ - -Invenio module for processing webhook events. - -- source code: ``_ -- releases: ``_ -- known issues: ``_ -- documentation: ``_ - -Core feature modules -==================== - -The **core feature modules** provide most common functionality that each digital -library instance is likely interested in using, such as record store, -search, deposit, or access control capabilities. - -invenio-access -++++++++++++++ - -Invenio module for common role based access control. - -- source code: ``_ -- releases: ``_ -- known issues: ``_ -- documentation: ``_ - -invenio-accounts -++++++++++++++++ - -Invenio user management and authentication. - -- source code: ``_ -- releases: ``_ -- known issues: ``_ -- documentation: ``_ - -invenio-collections -+++++++++++++++++++ - -Invenio module for organizing metadata into collections. - -- source code: ``_ -- releases: ``_ -- known issues: ``_ -- documentation: ``_ - -invenio-deposit -+++++++++++++++ - -Module for depositing record metadata and uploading files. - -- source code: ``_ -- releases: ``_ -- known issues: ``_ -- documentation: ``_ - -invenio-files-js -++++++++++++++++ - -- source code: ``_ -- releases: ``_ -- known issues: ``_ -- documentation: ``_ - -invenio-files-rest -++++++++++++++++++ - -Files download/upload REST API similar to S3 for Invenio. - -- source code: ``_ -- releases: ``_ -- known issues: ``_ -- documentation: ``_ - -invenio-indexer -+++++++++++++++ - -Indexer for Invenio. - -- source code: ``_ -- releases: ``_ -- known issues: ``_ -- documentation: ``_ - -invenio-jsonschemas -+++++++++++++++++++ - -Invenio module for building and serving JSONSchemas. - -- source code: ``_ -- releases: ``_ -- known issues: ``_ -- documentation: ``_ - -invenio-marc21 -++++++++++++++ - -Invenio module with nice defaults for MARC21 overlay. - -- source code: ``_ -- releases: ``_ -- known issues: ``_ -- documentation: ``_ - -invenio-oaiserver -+++++++++++++++++ - -Invenio module that implements OAI-PMH server. - -- source code: ``_ -- releases: ``_ -- known issues: ``_ -- documentation: ``_ - -invenio-pidstore -++++++++++++++++ - -Invenio module that stores and registers persistent identifiers. - -- source code: ``_ -- releases: ``_ -- known issues: ``_ -- documentation: ``_ - -invenio-previewer -+++++++++++++++++ - -Invenio module for previewing files. - -- source code: ``_ -- releases: ``_ -- known issues: ``_ -- documentation: ``_ - -invenio-query-parser -++++++++++++++++++++ - -Search query parser supporting Invenio and SPIRES search syntax. - -- source code: ``_ -- releases: ``_ -- known issues: ``_ -- documentation: ``_ - -invenio-records -+++++++++++++++ - -Invenio-Records is a metadata storage module. - -- source code: ``_ -- releases: ``_ -- known issues: ``_ -- documentation: ``_ - -invenio-records-files -+++++++++++++++++++++ - -Invenio modules that integrates records and files. - -- source code: ``_ -- releases: ``_ -- known issues: ``_ -- documentation: ``_ - -invenio-records-js -++++++++++++++++++ - -- source code: ``_ -- releases: ``_ -- known issues: ``_ -- documentation: ``_ - -invenio-records-rest -++++++++++++++++++++ - -REST API for invenio-records module. - -- source code: ``_ -- releases: ``_ -- known issues: ``_ -- documentation: ``_ - -invenio-records-ui -++++++++++++++++++ - -User interface for Invenio-Records. - -- source code: ``_ -- releases: ``_ -- known issues: ``_ -- documentation: ``_ - -invenio-search -++++++++++++++ - -Invenio module for information retrieval. - -- source code: ``_ -- releases: ``_ -- known issues: ``_ -- documentation: ``_ - -invenio-search-js -+++++++++++++++++ - -- source code: ``_ -- releases: ``_ -- known issues: ``_ -- documentation: ``_ - -invenio-search-ui -+++++++++++++++++ - -UI for Invenio-Search. - -- source code: ``_ -- releases: ``_ -- known issues: ``_ -- documentation: ``_ - -invenio-userprofiles -++++++++++++++++++++ - -Invenio module that adds userprofiles to the platform. - -- source code: ``_ -- releases: ``_ -- known issues: ``_ -- documentation: ``_ - -Additional feature modules -========================== - -The **additional feature modules** offer additional functionality suitable for -various particular use cases, such as the Integrated Library System, the -Multimedia Store, or the Data Repository. - -invenio-acquisitions -++++++++++++++++++++ - -- source code: ``_ -- releases: ``_ -- known issues: ``_ -- documentation: ``_ - -invenio-annotations -+++++++++++++++++++ - -- source code: ``_ -- releases: ``_ -- known issues: ``_ -- documentation: ``_ - -invenio-authorities -+++++++++++++++++++ - -- source code: ``_ -- releases: ``_ -- known issues: ``_ -- documentation: ``_ - -invenio-circulation -+++++++++++++++++++ - -Invenio module for the circulation of bibliographic items. - -- source code: ``_ -- releases: ``_ -- known issues: ``_ -- documentation: ``_ - -invenio-client -++++++++++++++ - -Command line client for Invenio. - -- source code: ``_ -- releases: ``_ -- known issues: ``_ -- documentation: ``_ - -invenio-comments -++++++++++++++++ - -Invenio module that adds record commenting feature. - -- source code: ``_ -- releases: ``_ -- known issues: ``_ -- documentation: ``_ - -invenio-communities -+++++++++++++++++++ - -Invenio module that adds support for communities. - -- source code: ``_ -- releases: ``_ -- known issues: ``_ -- documentation: ``_ - -invenio-csl-js -++++++++++++++ - -- source code: ``_ -- releases: ``_ -- known issues: ``_ -- documentation: ``_ - -invenio-csl-rest -++++++++++++++++ - -REST API for Citation Style Language styles. - -- source code: ``_ -- releases: ``_ -- known issues: ``_ -- documentation: ``_ - -invenio-github -++++++++++++++ - -Invenio module that adds GitHub integration to the platform. - -- source code: ``_ -- releases: ``_ -- known issues: ``_ -- documentation: ``_ - -invenio-groups -++++++++++++++ - -Invenio module that adds support for user groups. - -- source code: ``_ -- releases: ``_ -- known issues: ``_ -- documentation: ``_ - -invenio-ill -+++++++++++ - -- source code: ``_ -- releases: ``_ -- known issues: ``_ -- documentation: ``_ - -invenio-memento -+++++++++++++++ - -Invenio module makes your site Memento compliant. - -- source code: ``_ -- releases: ``_ -- known issues: ``_ -- documentation: ``_ - -invenio-metrics -+++++++++++++++ - -Invenio module for collecting and publishing metrics. - -- source code: ``_ -- releases: ``_ -- known issues: ``_ -- documentation: ``_ - -invenio-migrator -++++++++++++++++ - -Utilities for migrating past Invenio versions to Invenio 3.0. - -- source code: ``_ -- releases: ``_ -- known issues: ``_ -- documentation: ``_ - -invenio-oaiharvester -++++++++++++++++++++ - -Invenio module for OAI-PMH metadata harvesting between repositories. - -- source code: ``_ -- releases: ``_ -- known issues: ``_ -- documentation: ``_ - -invenio-openaire -++++++++++++++++ - -OpenAIRE service integration for Invenio repositories. - -- source code: ``_ -- releases: ``_ -- known issues: ``_ -- documentation: ``_ - -invenio-opendefinition -++++++++++++++++++++++ - -Invenio module integrating Invenio repositories and OpenDefinition. - -- source code: ``_ -- releases: ``_ -- known issues: ``_ -- documentation: ``_ - -invenio-orcid -+++++++++++++ - -ORCID integration for Invenio. - -- source code: ``_ -- releases: ``_ -- known issues: ``_ -- documentation: ``_ - -invenio-pages -+++++++++++++ - -Static pages module for Invenio. - -- source code: ``_ -- releases: ``_ -- known issues: ``_ -- documentation: ``_ - -invenio-previewer-ispy -++++++++++++++++++++++ - -Invenio previewer for ISPY visualisations. - -- source code: ``_ -- releases: ``_ -- known issues: ``_ -- documentation: ``_ - -invenio-sequencegenerator -+++++++++++++++++++++++++ - -Invenio module for generating sequences. - -- source code: ``_ -- releases: ``_ -- known issues: ``_ -- documentation: ``_ - -invenio-sipstore -++++++++++++++++ - -Submission Information Package store for Invenio. - -- source code: ``_ -- releases: ``_ -- known issues: ``_ -- documentation: ``_ - -invenio-tags -++++++++++++ - -Invenio module for record tagging by authenticated users. - -- source code: ``_ -- releases: ``_ -- known issues: ``_ -- documentation: ``_ - -invenio-xrootd -++++++++++++++ - -XRootD file storage support for Invenio. - -- source code: ``_ -- releases: ``_ -- known issues: ``_ -- documentation: ``_ - -Standalone utilities -==================== - -The **standalone utilities** developed for use in the Invenio ecysystem. - -cernservicexml -++++++++++++++ - -Small library to generate a CERN XSLS Service XML. - -- source code: ``_ -- releases: ``_ -- known issues: ``_ -- documentation: ``_ - -citeproc-py-styles -++++++++++++++++++ - -CSL styles. - -- source code: ``_ -- releases: ``_ -- known issues: ``_ -- documentation: ``_ - -datacite -++++++++ - -Python API wrapper for the DataCite Metadata Store API. - -- source code: ``_ -- releases: ``_ -- known issues: ``_ -- documentation: ``_ - -dcxml -+++++ - -Dublin Core XML generation from Python dictionaries. - -- source code: ``_ -- releases: ``_ -- known issues: ``_ -- documentation: ``_ - -dictdiffer -++++++++++ - -Dictdiffer is a library that helps you to diff and patch dictionaries. - -- source code: ``_ -- releases: ``_ -- known issues: ``_ -- documentation: ``_ - -dojson -++++++ - -DoJSON is a simple Pythonic JSON to JSON converter. - -- source code: ``_ -- releases: ``_ -- known issues: ``_ -- documentation: ``_ - -domapping -+++++++++ - -DoMapping generates Elasticsearch mappings from JSON Schemas. - -- source code: ``_ -- releases: ``_ -- known issues: ``_ -- documentation: ``_ - -doschema -++++++++ - -JSON Schema utility functions and commands. - -- source code: ``_ -- releases: ``_ -- known issues: ``_ -- documentation: ``_ - -flask-breadcrumbs -+++++++++++++++++ - -Flask-Breadcrumbs adds support for generating site breadcrumb navigation. - -- source code: ``_ -- releases: ``_ -- known issues: ``_ -- documentation: ``_ - -flask-celeryext -+++++++++++++++ - -Flask-CeleryExt is a simple integration layer between Celery and Flask. - -- source code: ``_ -- releases: ``_ -- known issues: ``_ -- documentation: ``_ - -flask-cli -+++++++++ - -Backport of Flask 1.0 new click integration. - -- source code: ``_ -- releases: ``_ -- known issues: ``_ -- documentation: ``_ - -flask-iiif -++++++++++ - -Flask-IIIF extension provides easy IIIF API standard integration. - -- source code: ``_ -- releases: ``_ -- known issues: ``_ -- documentation: ``_ - -flask-menu -++++++++++ - -Flask-Menu is a Flask extension that adds support for generating menus. - -- source code: ``_ -- releases: ``_ -- known issues: ``_ -- documentation: ``_ - -flask-notifications -+++++++++++++++++++ - -- source code: ``_ -- releases: ``_ -- known issues: ``_ -- documentation: ``_ - -flask-sitemap -+++++++++++++ - -- source code: ``_ -- releases: ``_ -- known issues: ``_ -- documentation: ``_ - -flask-sso -+++++++++ - -Flask-SSO extension that eases Shibboleth authentication. - -- source code: ``_ -- releases: ``_ -- known issues: ``_ -- documentation: ``_ - -idutils -+++++++ - -Small library for persistent identifiers used in scholarly communication. - -- source code: ``_ -- releases: ``_ -- known issues: ``_ -- documentation: ``_ - -intbitset -+++++++++ - -C-based extension implementing fast integer bit sets. - -- source code: ``_ -- releases: ``_ -- known issues: ``_ -- documentation: ``_ - -jsonresolver -++++++++++++ - -JSON data resolver with support for plugins. - -- source code: ``_ -- releases: ``_ -- known issues: ``_ -- documentation: ``_ - -kwalitee -++++++++ - -Kwalitee is a tool that runs static analysis checks on Git repository. - -- source code: ``_ -- releases: ``_ -- known issues: ``_ -- documentation: ``_ - -requirements-builder -++++++++++++++++++++ - -Build requirements files from setup.py requirements. - -- source code: ``_ -- releases: ``_ -- known issues: ``_ -- documentation: ``_ - -workflow -++++++++ - -Simple workflows for Python - -- source code: ``_ -- releases: ``_ -- known issues: ``_ -- documentation: ``_ - -xrootdpyfs -++++++++++ - -XRootDPyFS is a PyFilesystem interface to XRootD. - -- source code: ``_ -- releases: ``_ -- known issues: ``_ -- documentation: ``_ diff --git a/docs/technology/common-concepts.rst b/docs/technology/common-concepts.rst deleted file mode 100644 index f1d725e9f..000000000 --- a/docs/technology/common-concepts.rst +++ /dev/null @@ -1,110 +0,0 @@ -.. This file is part of Invenio - Copyright (C) 2014 CERN. - - Invenio 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 2 of the - License, or (at your option) any later version. - - Invenio 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 Invenio; if not, write to the Free Software Foundation, Inc., - 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. - -.. _common-concepts: - -Common concepts -=============== - -The description of concepts you will encounter here and there in the -Invenio. Our interpretation may differ from the practice found in -other products, so please read this carefully. - -1. sysno - (ALEPH|old) system number - - Stands for (ALEPH|old) system number only. Which means that, for - outside-CERN Invenio installations, stands for an 'old system - number' whatever it is, if they want to publicise it instead of our - internal auto-incremented Invenio record identifiers. - -2. recID - Invenio record identifier - - Each record has got an auto-incremented ID in the "bibrec" table - (formerly called "bibitem"). This is the basic "record identifier" - concept in Invenio. - -3. docID - eventual fulltext document identifier - - Each fulltext file may have eventual docID. This will permit us to - interconnect records (recID) with fulltext files (docID), if we - want to. At the moment there is only one-way connection from recID - to docID via HTTP field 856. This is ugly. I think we may - probably profit by introducing recID-docID relationship in several - ways: file protection, reference extraction, fulltext - indexing... (?!) - -4. field - logical field concept such as "reportnumber" - - A bibliographic record is composed of 'fields' such as title or - author. Note that we consider 'field' to be a logical concept, - that is compound and may consist of several physical MARC fields. - For example, "report number" field consists of several MARC fields - such as 088 $a, 037 $a, 909C0 $r. Another example: "first report - number" consist of only one MARC field, 037 $a. - -5. tag - physical field concept such as "088 $a". - - Having defined the concept of 'logical field', let's now turn to - the 'physical field' that denotes basically the concept of 'MARC - field' as defined in MARC-21 standard. In addition to tag, a field - may contain two identifiers to describe the data content, and - subfield codes to denote various parts of the content. See our - HOWTO MARC guide on this. - - Thus said, in the implementation of our bibliographic tables - (bibXXx) we have sort of generalized the term 'tag' to stand for:: - - tag = tag code + identifier1 + identifier2 + subfield code - - This convention, while taking some freedom from the MARC-21 - standard, enables us to write things like "field: base number, tag: - 909C0b, value: 11". If this interpretation is indeed too free with - respect to the standard usage of terms, we may change them in the - future. - -6. collection - here we distinguish (i) primary collection concept - and (ii) specific collection concept. - - The (i) primary collections are basic organizational structure of - how the records are grouped together in collections. The primary - collections are used in the navigable search interface under the - 'Narrow search' box. The (ii) specific collections present an - orthogonal view on the data organization, that is useful to group - together some records from different primary collections, if they - present a common pattern. The specific collections are used in the - search interface under the 'Focus on' box. - - The primary collections are defined mainly by the collection - identifier ("980 $a,b"); and the specific collections are as - defined by any query that is possible for a search engine to - execute (see also "dbquery" column in the "collection" table). - - In the past we used to use the term "catalogue", that is now - deprecated, and that can be interchanged with "collection". - -7. doctype - stands for web document type concept, used in WebSubmit - - The "document type" is used solely for submission purposes, and - fulltext access purposes ("setlink"-like). For example, a document - type "photo" may be used in many collections such as "Foo Photos", - "Bar PhotoLab", etc. Similarly, one collection can cover several - doctypes. (M:N relationship) - -8. baskets, alerts, settings - covering personal features - - Denote personal features, for which we previously used the terms - "shelf" and "profile" that are now deprecated. diff --git a/docs/technology/i18n.rst b/docs/technology/i18n.rst deleted file mode 100644 index e83ab62a2..000000000 --- a/docs/technology/i18n.rst +++ /dev/null @@ -1,24 +0,0 @@ -.. This file is part of Invenio - Copyright (C) 2015, 2016 CERN. - - Invenio 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 2 of the - License, or (at your option) any later version. - - Invenio 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 Invenio; if not, write to the Free Software Foundation, Inc., - 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. - -.. _i18n: - -I18N -==== - -.. include:: ../../ABOUT-NLS - :start-after: =============================== diff --git a/docs/technology/index.rst b/docs/technology/index.rst deleted file mode 100644 index 41e6024b5..000000000 --- a/docs/technology/index.rst +++ /dev/null @@ -1,29 +0,0 @@ -.. This file is part of Invenio - Copyright (C) 2015 CERN. - - Invenio 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 2 of the - License, or (at your option) any later version. - - Invenio 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 Invenio; if not, write to the Free Software Foundation, Inc., - 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. - -========== -Technology -========== - -.. toctree:: - :maxdepth: 2 - - common-concepts - python - git - i18n - docker diff --git a/docs/todo.rst b/docs/todo.rst new file mode 100644 index 000000000..7f4d178f7 --- /dev/null +++ b/docs/todo.rst @@ -0,0 +1,4 @@ +TODO +==== + +.. todolist:: diff --git a/docs/usersguide/accessing.rst b/docs/usersguide/accessing.rst new file mode 100644 index 000000000..65e16febd --- /dev/null +++ b/docs/usersguide/accessing.rst @@ -0,0 +1,2 @@ +Accessing content +================= diff --git a/docs/installation/installation-quick.rst b/docs/usersguide/installation-quick.rst similarity index 100% rename from docs/installation/installation-quick.rst rename to docs/usersguide/installation-quick.rst diff --git a/docs/usersguide/loading.rst b/docs/usersguide/loading.rst new file mode 100644 index 000000000..2d47f0f79 --- /dev/null +++ b/docs/usersguide/loading.rst @@ -0,0 +1,2 @@ +Loading content +=============== diff --git a/docs/usersguide/migrating.rst b/docs/usersguide/migrating.rst new file mode 100644 index 000000000..105caa26f --- /dev/null +++ b/docs/usersguide/migrating.rst @@ -0,0 +1,2 @@ +Migrating to v3 +--------------- diff --git a/docs/usersguide/orcid-login.rst b/docs/usersguide/orcid-login.rst new file mode 100644 index 000000000..9cee9d15e --- /dev/null +++ b/docs/usersguide/orcid-login.rst @@ -0,0 +1,2 @@ +Enabling ORCID login +==================== diff --git a/docs/usersguide/running.rst b/docs/usersguide/running.rst new file mode 100644 index 000000000..b0224bfe2 --- /dev/null +++ b/docs/usersguide/running.rst @@ -0,0 +1,11 @@ +Running Invenio +=============== + +Starting the webserver +---------------------- + +Starting job queue +------------------ + +Using the CLI +------------- diff --git a/docs/usersguide/tutorial/customize-logo.rst b/docs/usersguide/tutorial/customize-logo.rst new file mode 100644 index 000000000..f7342daf0 --- /dev/null +++ b/docs/usersguide/tutorial/customize-logo.rst @@ -0,0 +1,2 @@ +Part 3: Customize logo and name +=============================== diff --git a/docs/usersguide/tutorial/customize-templates.rst b/docs/usersguide/tutorial/customize-templates.rst new file mode 100644 index 000000000..5a259ea90 --- /dev/null +++ b/docs/usersguide/tutorial/customize-templates.rst @@ -0,0 +1,2 @@ +Part 4: Customize templates +=========================== diff --git a/docs/configuration/index.rst b/docs/usersguide/tutorial/index.rst similarity index 88% rename from docs/configuration/index.rst rename to docs/usersguide/tutorial/index.rst index 680d0a123..2e40366a8 100644 --- a/docs/configuration/index.rst +++ b/docs/usersguide/tutorial/index.rst @@ -1,25 +1,29 @@ .. This file is part of Invenio Copyright (C) 2015 CERN. Invenio 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 2 of the License, or (at your option) any later version. Invenio 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 Invenio; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. -============= -Configuration -============= + +First steps +=========== .. toctree:: :maxdepth: 2 - overlay + prerequisites + install + records + customize-logo + customize-templates diff --git a/docs/usersguide/tutorial/install.rst b/docs/usersguide/tutorial/install.rst new file mode 100644 index 000000000..3ae67cb27 --- /dev/null +++ b/docs/usersguide/tutorial/install.rst @@ -0,0 +1,2 @@ +Part 1: Install and configuring Invenio +======================================= diff --git a/docs/usersguide/tutorial/prerequisites.rst b/docs/usersguide/tutorial/prerequisites.rst new file mode 100644 index 000000000..5a14fd0ba --- /dev/null +++ b/docs/usersguide/tutorial/prerequisites.rst @@ -0,0 +1,2 @@ +Install prerequisites +===================== diff --git a/docs/usersguide/tutorial/records.rst b/docs/usersguide/tutorial/records.rst new file mode 100644 index 000000000..c1a13fcda --- /dev/null +++ b/docs/usersguide/tutorial/records.rst @@ -0,0 +1,2 @@ +Part 2: Create and search your first record +=========================================== diff --git a/setup.py b/setup.py index 0bdaca256..d80678087 100644 --- a/setup.py +++ b/setup.py @@ -1,178 +1,180 @@ # -*- coding: utf-8 -*- # # This file is part of Invenio. # Copyright (C) 2013, 2014, 2015, 2016 CERN. # # Invenio 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 2 of the # License, or (at your option) any later version. # # Invenio 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 Invenio; if not, write to the # Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, # MA 02111-1307, USA. # # In applying this license, CERN does not # waive the privileges and immunities granted to it by virtue of its status # as an Intergovernmental Organization or submit itself to any jurisdiction. """Invenio Digital Library Framework.""" import os import sys from setuptools import find_packages, setup from setuptools.command.test import test as TestCommand readme = open('README.rst').read() history = open('CHANGES.rst').read() tests_require = [ 'check-manifest>=0.25', 'coverage>=4.0', 'isort>=4.2.2', 'pydocstyle>=1.0.0', 'pytest-cache>=1.0', 'pytest-cov>=1.8.0', 'pytest-pep8>=1.0.6', 'pytest>=2.8.0', ] invenio_db_version = '>=1.0.0b3,<1.1.0' extras_require = { - 'access': [ - 'invenio-access>=1.0.0a11,<1.1.0', + # Flavours + 'ils': [ + 'invenio-app-ils>=1.0.0.dev0,<1.1.0', + ], + # Bundles + 'base': [ + 'invenio-admin>=1.0.0b1,<1.1.0', + 'invenio-assets>=1.0.0b6,<1.1.0', + 'invenio-formatter>=1.0.0b1,<1.1.0', + 'invenio-logging>=1.0.0b1,<1.1.0', + 'invenio-mail>=1.0.0b1,<1.1.0', + 'invenio-rest>=1.0.0a10,<1.1.0', + 'invenio-theme>=1.0.0b1,<1.1.0', ], - 'accounts': [ + 'auth': [ + 'invenio-access>=1.0.0a11,<1.1.0', 'invenio-accounts>=1.0.0b1,<1.1.0', + 'invenio-oauth2server>=1.0.0a14,<1.1.0', + 'invenio-oauthclient>=1.0.0a12,<1.1.0', + 'invenio-userprofiles>=1.0.0a9,<1.1.0', ], - 'records': [ - 'dojson>=1.2.1', + 'metadata': [ + 'invenio-indexer>=1.0.0a9,<1.1.0', + 'invenio-jsonschemas>=1.0.0a3,<1.1.0', + 'invenio-oaiserver>=1.0.0a12,<1.1.0', 'invenio-pidstore>=1.0.0b1,<1.1.0', - 'invenio-records>=1.0.0b1,<1.1.0', + 'invenio-records-rest>=1.0.0a18,<1.1.0', 'invenio-records-ui>=1.0.0a8,<1.1.0', - 'invenio-records-rest>=1.0.0a17,<1.1.0', - ], - 'search': [ + 'invenio-records>=1.0.0b1,<1.1.0', + 'invenio-search-ui>=1.0.0a6,<1.1.0', 'invenio-search>=1.0.0a9,<1.1.0', ], - 'theme': [ - 'invenio-assets>=1.0.0b4,<1.1.0', - 'invenio-theme>=1.0.0a14,<1.1.0', - ], - 'utils': [ - 'invenio-mail>=1.0.0a5,<1.1.0', - 'invenio-rest>=1.0.0a10,<1.1.0', - 'invenio-logging>=1.0.0a3,<1.1.0', - ], + # Databases 'mysql': [ 'invenio-db[mysql]' + invenio_db_version, ], 'postgresql': [ 'invenio-db[postgresql]' + invenio_db_version, ], + # Elasticsearch versions + 'elasticsearch2': [ + 'elasticsearch>=2.0.0,<3.0.0', + 'elasticsearch-dsl>=2.0.0,<3.0.0', + ], + # Docs and test dependencies 'docs': [ - 'Sphinx>=1.4.2', + 'Sphinx>=1.5.1', ], 'tests': tests_require, } # # Aliases allow for easy installation of a specific type of Invenio instances. # pip install invenio[repository] # aliases = { - 'minimal': [ - 'accounts', - 'theme', - 'utils', - ], - 'full': [ - 'access', - 'accounts', - 'records', - 'search', - 'theme', - 'utils', - ], + } for name, requires in aliases.items(): extras_require[name] = [] for r in requires: - extras_require[name].extend(extras_require[r]) + extras_require[name].extend( + extras_require[r] if r in extras_require else [r] + ) # All alias to install every possible dependency. extras_require['all'] = [] for name, reqs in extras_require.items(): if name in {'mysql', 'postgresql'}: continue extras_require['all'].extend(reqs) # # Minimal required packages for an Invenio instance (basically just the # Flask application loading). # setup_requires = [ 'pytest-runner>=2.6.2', ] install_requires = [ 'Flask>=0.11.1', - 'elasticsearch>=2.0.0,<3.0.0', - 'elasticsearch-dsl>=2.0.0,<3.0.0', - 'invenio-base>=1.0.0a6,<1.1.0', - 'invenio-celery>=1.0.0a2,<1.1.0', - 'invenio-config>=1.0.0a1,<1.1.0', - 'invenio-i18n>=1.0.0a1,<1.1.0', + 'invenio-base>=1.0.0a14,<1.1.0', + 'invenio-celery>=1.0.0b2,<1.1.0', + 'invenio-config>=1.0.0b2,<1.1.0', + 'invenio-i18n>=1.0.0b3,<1.1.0', ] packages = find_packages() # Get the version string. Cannot be done with import! g = {} with open(os.path.join('invenio', 'version.py'), 'rt') as fp: exec(fp.read(), g) version = g['__version__'] setup( name='invenio', version=version, description=__doc__, long_description=readme + '\n\n' + history, keywords='Invenio digital library framework', license='GPLv2', author='CERN', author_email='info@inveniosoftware.org', url='https://github.com/inveniosoftware/invenio', packages=packages, zip_safe=False, include_package_data=True, platforms='any', entry_points={}, extras_require=extras_require, install_requires=install_requires, setup_requires=setup_requires, tests_require=tests_require, classifiers=[ 'Environment :: Web Environment', 'Intended Audience :: Developers', 'License :: OSI Approved :: GNU General Public License v2 (GPLv2)', 'Operating System :: OS Independent', 'Programming Language :: Python', 'Topic :: Internet :: WWW/HTTP :: Dynamic Content', 'Topic :: Software Development :: Libraries :: Python Modules', 'Programming Language :: Python :: 2', 'Programming Language :: Python :: 2.7', 'Programming Language :: Python :: 3', 'Programming Language :: Python :: 3.5', 'Development Status :: 3 - Alpha', ], )