[PATCH sherpa] [doc] Update and add more documentation

Sylvain Thenault sylvain.thenault at logilab.fr
Tue Apr 11 15:40:59 CEST 2017


# HG changeset patch
# User Sylvain Thénault <sylvain.thenault at logilab.fr>
# Date 1490980373 -7200
#      Fri Mar 31 19:12:53 2017 +0200
# Node ID 1dfa18f554b60378d24a619f0ddbc48da0415453
# Parent  43ab707fda2e9a8a1603d670eb54c3ab66ac1c86
[doc] Update and add more documentation

diff --git a/doc/conf.py b/doc/conf.py
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -41,19 +41,19 @@ source_suffix = '.rst'
 
 # The master toctree document.
 master_doc = 'index'
 
 # General information about the project.
-project = u'Agape 2'
-copyright = u'2016, Logilab'
+project = u'SHERPA'
+copyright = u'2017, Logilab'
 
 # 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.
-version = '0.1'
+version = '1.0'
 # 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.
@@ -174,11 +174,11 @@ html_use_index = False
 
 # This is the file name suffix for HTML files (e.g. ".xhtml").
 #html_file_suffix = None
 
 # Output file base name for HTML help builder.
-htmlhelp_basename = 'Agape2-Refdoc'
+htmlhelp_basename = 'SHERPA-Refdoc'
 
 
 # -- Options for LaTeX output ---------------------------------------------
 
 latex_elements = {
@@ -194,11 +194,11 @@ latex_elements = {
 
 # 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 = [
-  ('index', 'Agape2.tex', u'Agape2 Documentation',
+  ('index', 'SHERPA.tex', u'SHERPA Documentation',
    u'Logilab', 'manual'),
 ]
 
 # The name of an image file (relative to this directory) to place at the top of
 # the title page.
@@ -224,11 +224,11 @@ latex_documents = [
 # -- Options for manual page output ---------------------------------------
 
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [
-    ('index', 'agape2', u'Agape2 Documentation',
+    ('index', 'sherpa', u'SHERPA Documentation',
      [u'Logilab'], 1)
 ]
 
 # If true, show URL addresses after external links.
 #man_show_urls = False
@@ -238,12 +238,12 @@ man_pages = [
 
 # Grouping the document tree into Texinfo files. List of tuples
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
-  ('index', 'Agape2', u'Agape2 Documentation',
-   u'Logilab', 'Agape2', 'One line description of project.',
+  ('index', 'SHERPA', u'SHERPA Documentation',
+   u'Logilab', 'SHERPA', 'One line description of project.',
    'Miscellaneous'),
 ]
 
 # Documents to append as an appendix to all manuals.
 #texinfo_appendices = []
diff --git a/doc/configuration.rst b/doc/configuration.rst
--- a/doc/configuration.rst
+++ b/doc/configuration.rst
@@ -4,29 +4,40 @@ Gestion de configuration
 L'application est construite sur le cadre applicatif CubicWeb_. À ce titre, c'est elle même un
 "cube" (i.e. un composant CubicWeb), dont la structure générale est décrite ici_.
 
 Elle s'appuie sur les composants logiciels suivants :
 
-* le `cadre applicatif CubicWeb`_ lui-même (>= 3.23) ;
+* le cadre applicatif CubicWeb_ lui-même (>= 3.24) ;
+
+* `cubicweb-sherpa`_, l'application SHERPA proprement dite, agrégeant les différents composants
+  ci-dessous ;
 
 * `cubicweb-seda`_, cube implémentant le modèle de données SEDA 2, complet et simplifié, ainsi que
   les fonctions d'export ;
 
-* `cubicweb-registration`_, cube implémentant la création de compte sans passer par un
-  administrateur ;
+* `cubicweb-eac`_, cube implémentant le modèle de données EAC, et permettant notamment d'importer
+  puis de réexporter les notices d'autorités ;
+
+* `cubicweb-skos`_, cube implémentant le modèle de données SKOS, et permettant notamment d'importer
+  puis de réexporter des vocabulaires au format SKOS_ pour la gestion des thésaurus et autres
+  vocabulaires contrôlés;
+
+* `cubicweb-registration`_ , cube permettant de se créer un compte sur la plateforme sans passer par
+  un administrateur ;
+
+* `cubicweb-forgotpwd`_ , cube permettant de remettre à zéro son mot de passe en cas d'oubli ;
 
 * `cubicweb-rememberme`_ , cube permettant de rester connecter d'une fois à l'autre.
 
-Les dépendances de ces logiciels ne sont pas indiquées ici, mais comprennent notamment le cube
-`skos`_ qui implémente le modèle de données et l'import / export du format SKOS_ qui est utilisé
-pour la gestion des thésaurus et autres vocabulaires contrôlés.
-
 
 
 .. _CubicWeb: https://cubicweb.org
 .. _ici: http://cubicweb.readthedocs.io/en/3.23/book/devrepo/cubes/layout/
 .. _`cadre applicatif CubicWeb`: https://www.cubicweb.org/project/cubicweb
 .. _`cubicweb-seda`: https://www.cubicweb.org/project/cubicweb-seda
+.. _`cubicweb-eac`: https://www.cubicweb.org/project/cubicweb-eac
+.. _`cubicweb-skos`: https://www.cubicweb.org/project/cubicweb-skos
+.. _`cubicweb-forgotpwd`: https://www.cubicweb.org/project/cubicweb-forgotpwd
 .. _`cubicweb-registration`: https://www.cubicweb.org/project/cubicweb-registration
 .. _`cubicweb-rememberme`: https://www.cubicweb.org/project/cubicweb-rememberme
 .. _`skos`: https://www.cubicweb.org/project/cubicweb-skos
 .. _SKOS_: https://fr.m.wikipedia.org/wiki/Simple_Knowledge_Organization_System
diff --git a/doc/eac.rst b/doc/eac.rst
new file mode 100644
--- /dev/null
+++ b/doc/eac.rst
@@ -0,0 +1,29 @@
+=======
+EAC-CPF
+=======
+
+Le référentiel fournit une implémentation de EAC-CPF_ relativement complète. Les notices d'autorités
+peuvent être créés ou importés directement dans l'interface web ou bien importés en ligne de
+commande. Pour le moment, l'interface utilisateur permet néanmoins d'éditer qu'un petit
+sous-ensemble du modèles.
+
+.. section sur les balises supportées ou non
+.. include:: ../../cubicweb-eac/doc/supported.rst
+
+
+Import de notices d'autorités en ligne de commande
+==================================================
+
+Pour importer un fichier EAC-CPF, vous pouvez utiliser la commande 'eac-import' de `cubicweb-ctl` :
+
+::
+
+    CW_MODE=user cubicweb-ctl eac-import sherpa fichier.rdf
+
+
+Export des notices en EAC
+=========================
+
+Pour chaque forme du nom, l'attribute 'parties' est découpée selon le caractère ", " puis chaque
+élément est inséré dans une balise ``part``. C'est le traitement symétrique à ce qui est fait durant
+l'import (concaténation des différentes balises ``part`` avec le séparateur ", ")
\ No newline at end of file
diff --git a/doc/index.rst b/doc/index.rst
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -1,17 +1,18 @@
 .. -*- coding: utf-8 -*-
 
 .. _contents:
 
 =====================================================
-Agape 2 - Documentation
+SHERPA - Documentation
 =====================================================
 
 .. toctree::
    :maxdepth: 2
 
    intro
    configuration
+   install
    seda
    profils
-
-..   ChangeLog_fr
\ No newline at end of file
+   skos
+   eac
diff --git a/doc/install.rst b/doc/install.rst
new file mode 100644
--- /dev/null
+++ b/doc/install.rst
@@ -0,0 +1,174 @@
+============
+Installation
+============
+
+La doc suivante suppose que vous êtes sur une distribution Red-Hat / CentOS, mais cela pourrait
+aussi être une distribution Debian / Ubuntu en utilisant ``apt-get`` plutôt que ``yum``. La
+principale condition est d'utiliser un système avec une version récente de python (2.7) et ``pip``.
+
+Le mieux est généralement de commencer par installer ``virtualenv`` avec ``pip`` afin d'avoir la
+dernière version disponible : ::
+
+  pip install virtualenv
+
+
+Configuration du serveur PostgreSQL
+-----------------------------------
+
+Si vous n'en n'avez pas encore un disponible, il faut commencer par installer un serveur PostgreSQL
+(pas nécessairement sur la même machine que le réferentiel). Sur une distribution Red-Hat / CentOS,
+il faut commencer par installer les paquets suivants :
+
+::
+
+    yum install postgresql94-contrib
+    yum install postgresql94-plpython
+    yum install postgresql94-server
+    yum install mailcap # pour /etc/mime.types
+
+Créer et démarrer un *cluster* PostgreSQL
+
+::
+
+    service postgresql-9.4 initdb
+    service postgresql-9.4 start
+
+En tant qu'utilisateur ``postgres`` (par exemple ``su - postgres``),
+créer un nouveau compte d'accès à Postgres :
+
+::
+
+    createuser --superuser --login --pwprompt cubicweb
+
+De retour en ``root``, éditer le fichier ``/var/lib/pgsql/9.4/data/pg_hba.conf``
+pour donner les droits d'accès à l'utilisateurs ``cubicweb`` fraichement créé :
+
+::
+
+    local   all   cubicweb    md5
+
+
+.. warning::
+
+    L'ordre des directives de ce fichier est important. La directive concernant
+    l'utilisateur ``cubicweb`` doit précéder celles déjà présentes dans le
+    fichier. Dans le cas contraire, elle sera ignorée.
+
+Enfin, on relance PostgreSQL pour qu'il prenne en compte les modifications :
+
+::
+
+    service postgresql-9.4 reload
+
+Pour s'assurer du bon fonctionnement de PostgreSQL et du rôle ``cubicweb``, la
+commande suivante doit afficher le contenu du *cluster* sans erreur :
+
+::
+
+    psql -U cubicweb -l
+
+
+Installation de l'application
+-----------------------------
+
+Nous recommandons d'installer le code du référentiel avec un utilisateur
+standard (pas *root*) :
+
+::
+
+    adduser sherpa
+    su - sherpa
+
+et dans un virtualenv_, qu'il convient donc de créer puis d'activer :
+
+::
+    virtualenv sherpa-venv
+    . sherpa-venv/bin/activate
+
+Par la suite, nous supposerons que vous tapez les commandes indiquées en tant qu'utilisateur
+`sherpa` et avec le *virtualenv* activé.
+
+Installer le référentiel :
+
+::
+
+    pip install cubicweb-sherpa
+
+
+Création de l'instance
+----------------------
+
+Une fois le cube sherpa et ses dépendances installées, il reste à créer une
+instance de celui-ci :
+
+::
+
+  CW_MODE=user cubicweb-ctl create sherpa sherpa
+
+.. note ::
+
+    La phase finale de création prend quelques minutes, afin de remplir la base
+    avec quelques données nécessaires au bon fonctionnement de l'application.
+
+* Laisser le choix par défaut à toutes les questions ;
+
+* Choisir un login / mot de passe administrateur sécurisé (admin/admin est une
+  mauvaise idée, nous recommandons d'installer le paquet ``pwgen`` et de
+  générer un mot de passe aléatoire avec la commande ``pwgen 20``).
+
+Selon votre configuration postgres, vous pouvez avoir à modifier le fichier sources pour y spécifier
+les informations de connection au server (hôte, port, utilisateur et mot de passe). Le plus simple
+est de répondre non à la question "Run db-create to create the system database ?", d'éditer le
+fichier `~/etc/cubicweb.d/sherpa/sources` puis de reprendre le processus d'initialisation en
+tapant :
+
+::
+
+  CW_MODE=user cubicweb-ctl db-create sherpa
+
+Vous pouvez maintenant lancer l'instance :
+
+::
+
+  CW_MODE=user cubicweb-ctl pyramid sherpa
+
+L'instance est désormais lancée et disponible sur le port 8080.
+
+Pour une instance de production, il est recommandé d'utilisé un serveur d'application WSGI tel que
+`gunicorn`_ et un superviseur tel que `supervisor`_.
+
+
+Mise à jour de l'instance
+=========================
+
+.. warning::
+
+  Il y aura donc une interruption de service pendant cette opération
+
+Lors qu'une nouvelle version est livrée, il faut commencer par mettre à jour le code de
+l'application. Le plus simple pour cela est de supprimer le *virtualenv* et de le recréer. Si vous
+avez installé le référentiel avec pip :
+
+::
+
+    # Ctrl-C pour couper l'instance qui tourne
+    rm -rf sherpa-venv
+    virtualenv sherpa-venv
+    . sherpa-venv/bin/activate
+    pip install cubicweb-sherpa
+
+Puis il reste à mettre à jour l'instance CubicWeb. Pour une installation avec pip :
+
+::
+
+    CW_MODE=USER cubicweb-ctl upgrade sherpa
+    CW_MODE=USER cubicweb-ctl pyramid sherpa
+
+La commande `cubicweb-ctl upgrade` pose un certain nombre de questions, auxquelles il faut toujours
+répondre par oui (en tapant 'y' ou Entrée directement). Un backup de la base de données est effectué
+avant la migration afin de pouvoir rejouer une migration en cas de problement.
+
+.. _pip: https://pip.pypa.io/
+.. _virtualenv: https://virtualenv.pypa.io/
+.. _gunicorn: http://gunicorn.org/
+.. _supervisor: http://supervisord.org/
diff --git a/doc/intro.rst b/doc/intro.rst
--- a/doc/intro.rst
+++ b/doc/intro.rst
@@ -1,9 +1,9 @@
 Présentation
 ------------
 
-Agape 2 est une application Web permettant de générer des profils SEDA_. Elle prend la suite de
+SHERPA est une application Web permettant de générer des profils SEDA_. Elle prend la suite de
 l'application de bureau Agape_, en supportant la `version 2 du SEDA`_ et en ajoutant une dimension
 collaborative.
 
 Principales fonctionnalités :
 
diff --git a/doc/profils.rst b/doc/profils.rst
--- a/doc/profils.rst
+++ b/doc/profils.rst
@@ -1,1 +1,1 @@
-.. include:: ../../seda/doc/profils.rst
\ No newline at end of file
+.. include:: ../../cubicweb-seda/doc/profils.rst
\ No newline at end of file
diff --git a/doc/seda.rst b/doc/seda.rst
--- a/doc/seda.rst
+++ b/doc/seda.rst
@@ -1,1 +1,2 @@
-.. include:: ../../seda/doc/seda.rst
\ No newline at end of file
+
+.. include:: ../../cubicweb-seda/doc/seda2_compat.rst
\ No newline at end of file
diff --git a/doc/skos.rst b/doc/skos.rst
new file mode 100644
--- /dev/null
+++ b/doc/skos.rst
@@ -0,0 +1,48 @@
+====
+SKOS
+====
+
+SHERPA fournit une implémentation de SKOS_. Les thésaurus ou vocabulaires contrôlés peuvent
+être créés ou importés directement dans l'interface web ou bien importés en ligne de commande.
+
+Notez qu'un vocabulaire importé peut être rattaché à une **source** ou non. L'intérêt de passer par
+une source est que cette dernière permet de conserver l'URL d'origine du vocabulaire et ainsi de le
+(re)synchroniser plus tard. De plus le vocabulaire et ses concepts sont identifiés comme provenant
+de cette source.
+
+Dans l'interface web, le seul moyen accessible pour importer un vocabulaire est d'ajouter une
+source. Si vous souhaitez importer un fichier SKOS directement, il faut utiliser l'import en ligne
+de commande expliqué ci-dessous.
+
+
+Import de thésaurus en ligne de commande
+========================================
+
+Lorsqu'il est lancé par l'interface web, l'import de thésaurus SKOS ne peut
+utiliser les optimisations qui deviennent nécessaires dès que le thésaurus est
+de taille conséquente (plus d'une centaine de concepts). En effet ces
+optimisations nécessitent que l'import soit effectué sans que d'autres
+connexions à la base de données soient actives (ce qui implique donc de stopper
+le serveur web pendant ce temps).
+
+Pour importer un fichier SKOS RDF sans que celui-ci soit rattaché à une source de données, vous
+pouvez utiliser la commande 'skos-import' de `cubicweb-ctl` :
+
+::
+
+    CW_MODE=user cubicweb-ctl skos-import sherpa fichier.rdf
+
+Pour déclencher l'import initial ou la synchronisation de données SKOS RDF dont l'URL a été
+spécifiée par l'ajout d'une source dans l'interface web, vous pouvez utiliser la commande
+'source-sync' :
+
+::
+
+    CW_MODE=user cubicweb-ctl source-sync sherpa <nom de la source>
+
+Ces deux exemples supposent que votre instance se nomme "saem" et que vous avez coupé l'interface
+web au préalable (``cubicweb-ctl stop sherpa`` ou ``supervisorctl stop sherpa`` si votre instance est
+supervisée).
+
+
+.. _SKOS: https://fr.wikipedia.org/wiki/Simple_Knowledge_Organization_System
diff --git a/tox.ini b/tox.ini
--- a/tox.ini
+++ b/tox.ini
@@ -34,5 +34,13 @@ commands = flake8 --exit-zero --show-sou
 format = pylint
 ignore = W503
 max-line-length = 100
 max-complexity = 12
 exclude = setup.py,doc/conf.py,cubicweb_sherpa/migration/*,.tox/*
+
+[testenv:doc]
+changedir = doc
+whitelist_externals =
+  sphinx-build
+deps =
+  sphinx
+commands = sphinx-build -b html -d doctrees .  html


More information about the saem-devel mailing list