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

Philippe Pepiot philippe.pepiot at logilab.fr
Tue Apr 11 16:57:39 CEST 2017


On 04/11/2017 03:40 PM, Sylvain Thenault wrote:
> # 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;


For consistency you could add an extra space before ';' here (not sure 
if it's relevant in rst syntax).


> +
> +* `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


How this include work ? It suppose that cubicweb-eac is installed in the 
same virtualenv ? That's the reason of recent changesets about 
distributing doc with the python package ?


> +
> +
> +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
                                ^
                                attribut ?


> +é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


Maybe adding --upgrade or --ignore-installed could help if virtualenv 
has already been installed.


> +
> +
> +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,
                                                   ^
                                                   référentiel


> +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
                        ^
                        connexion au serveur


> +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
                                                             ^
                                                             sherpa


> +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