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

Sylvain Thénault sylvain.thenault at logilab.fr
Wed Apr 12 08:44:33 CEST 2017


Le 11/04/2017 à 16:57, Philippe Pepiot a écrit :
> 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).

rst don't mind, french typography rules do :)

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

yep that's it. Let's keep that for a follow-up :)

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

which one would you recommand ?

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

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

-- 
Sylvain Thénault, LOGILAB, Paris (01.45.32.03.12) - Toulouse (05.62.17.16.42)
Formations Python, Debian, Méth. Agiles: http://www.logilab.fr/formations
Développement logiciel sur mesure:       http://www.logilab.fr/services
CubicWeb, the semantic web framework:    http://www.cubicweb.org



More information about the saem-devel mailing list