Merge of 'dev-dc' branch and little updates
authorThierry Florac <thierry.florac@onf.fr>
Mon, 26 Mar 2018 10:38:06 +0200
changeset 28 a7332a53e6dc
parent 23 c4d22fabf017 (diff)
parent 27 4cddbff4269f (current diff)
child 29 78f842f992a0
child 46 5fe8d5ffccde
Merge of 'dev-dc' branch and little updates
buildout.cfg
setup.py
src/pyams_user_guide.egg-info/requires.txt
src/source/quickstart.rst
--- a/buildout.cfg	Fri Mar 23 11:50:01 2018 +0100
+++ b/buildout.cfg	Mon Mar 26 10:38:06 2018 +0200
@@ -93,6 +93,7 @@
 recipe = collective.recipe.sphinxbuilder
 eggs =
     ${package:eggs}
+    sphinx_rtd_theme
 source = ${buildout:directory}/src/source
 build = ${buildout:directory}/src/build
 
--- a/setup.py	Fri Mar 23 11:50:01 2018 +0100
+++ b/setup.py	Mon Mar 26 10:38:06 2018 +0200
@@ -62,6 +62,7 @@
       extras_require=dict(test=tests_require),
       install_requires=[
           'setuptools',
+          'sphinx_rtd_theme'
           # -*- Extra requirements: -*-
       ],
       entry_points={})
--- a/src/pyams_user_guide.egg-info/requires.txt	Fri Mar 23 11:50:01 2018 +0100
+++ b/src/pyams_user_guide.egg-info/requires.txt	Mon Mar 26 10:38:06 2018 +0200
@@ -1,4 +1,5 @@
 setuptools
+sphinx_rtd_theme
 
 [test]
 pyramid_zcml
--- a/src/source/quickstart.rst	Fri Mar 23 11:50:01 2018 +0100
+++ b/src/source/quickstart.rst	Mon Mar 26 10:38:06 2018 +0200
@@ -13,25 +13,20 @@
 0. Before starting
 ++++++++++++++++++
 
-
-**a. Package required**
+Required packages
+-----------------
 
-
-PyAMS relies on Python packages for which you must have system packages available in your environment.
-
+PyAMS relies on system and Python packages which you must have been previously installed in your environment.
 
 .. note::
 
-    - C/C++ compiler like **GCC**
-    - **Python 3.5*** with development headers or **Cython3** for better optimization of several packages
-    - Cache server, like **Redis** or **Memcached**.
+    - a C/C++ compiler like **GCC**
+    - **Python 3.5*** with development headers; **Cython3** for better optimization of several packages
+    - a cache server, like **Redis** or **Memcached**.
+    - Several libraries with their development headers: *libjpeg*, *libpng*, *libfreetype*, *libxml2* and *libxslt*
+      (and *libpq* if you want to use PostgreSQL, *libldap* if you want to use LDAP authentication...).
 
-    - Several libraries with their development headers:
-
-        => *libjpeg*, *libpng*, *libfreetype*, *libxml2* and *libxslt* (and *libpq* if you want to use PostgreSQL)
-
-
-*PyAMS may be compatible with other versions but has only been completely tested with this version until now
+* PyAMS may be compatible with other versions but has only been completely tested with this version until now.
 
 On a Debian GNU/Linux:
 
@@ -43,8 +38,8 @@
      $ apt-get install libjpeg-dev libpng-dev libfreetype6-dev libxml2-dev libxslt1-dev
 
 
-**b. Initialize virtual environment**
-
+Initialize virtual environment
+------------------------------
 
 We are creating a virtual environment in */var/local/env*
 
@@ -55,24 +50,23 @@
     $ virtualenv --python=python3.5 env
     $ source env/bin/activate
 
-To use PyAMS templates *cookiecutter* is required
+To use PyAMS templates, the *cookiecutter* tool is required:
 
 .. code-block:: bash
 
     (env)$ pip3.5 install cookiecutter
 
 
-
 1. Create ZODB
 ++++++++++++++
 
-We are creating a local ZODB using ZEO server using cookiecutter template
+We are creating a local ZODB using a "ZEO server" cookiecutter template.
 
-.. tip:: To know more about ZODB storage you can see :ref:`zodb`.
+.. tip:: To know more about ZODB storages you can see :ref:`zodb`.
 
 .. note::
 
-    In this example, ZEO server instance will run as UNIX user and group. For a production
+    In this example, ZEO server instance will run as current UNIX user and group. For a production
     environment, it's better to use dedicated service user and group.
 
 Run cookiecutter:
@@ -89,13 +83,13 @@
     pyams_release [latest]:
     project_name [ZEO_server]: ZEO_pyams
     project_slug [zeo_pyams]:
-    eggs_directory [eggs]: /var/local/eggs  #Python eggs will be stored into */var/local/eggs* directory.
-    run_user [zeo]: mylogin
-    run_group [zeo]: mygroup
+    eggs_directory [eggs]: /var/local/eggs    # Python eggs will be stored into */var/local/eggs* directory.
+    run_user [zeo]: mylogin                   # current user ID
+    run_group [zeo]: mygroup                  # current user group
     zeo_server_port [8100]:
     zeo_storage [pyams]:
     zeo_pack_report [root@localhost]: email@my-domain.com
-    logs_directory [/var/log/zeo/zeo_pyams]:  #Absolute path is mandatory
+    logs_directory [/var/log/zeo/zeo_pyams]:  # An absolute path is mandatory!!!
 
     Your ZEO environment is initialized.
     To finalize it\'s creation, just type:
@@ -104,7 +98,7 @@
     - ./bin/buildout
 
 
-In *zeo_pyams* folder, execute *bootstrap.py*...
+In *zeo_pyams* folder, execute *bootstrap.py*:
 
 .. code-block:: bash
 
@@ -117,7 +111,7 @@
     Generated script '/var/local/env/zeo_pyams/bin/buildout'.
 
 
-...and then run *buildout*
+And then run final *buildout*:
 
 .. code-block:: bash
 
@@ -145,27 +139,23 @@
     daemon process started, pid=26230
 
 
-
-
 2. Create application instance
-+++++++++++++++++++++++++++
+++++++++++++++++++++++++++++++
 
 Application instance will be created in */var/local/env/pyams* via another coockiecutter template:
 
-.. tip::
-
 .. code-block:: bash
 
     (env)$ cd /var/local/env
     (env)$ cookiecutter hg+http://hg.ztfy.org/pyams/scaffolds/pyams
 
 
-Configuration
+.. tip:: Configuration
 
-.. tip::
-
-    1. The variable *$((INSTALL))* is the path path to current folder
-    2. You will be invited setup supplementary services like **elastics search** but you must to install them on your own.
+    1. The variable **$((INSTALL))** is the path to current folder; it will be replaced automatically by cookiecutter
+       after application creation
+    2. You will be invited to setup additional services like **Elasticsearch** but you must install them on
+       your own.
 
 
 .. code-block:: bash
@@ -177,9 +167,9 @@
     webapp_name [webapp]:
     webapp_port [6543]:
     eggs_directory [eggs]:
-    logs_directory [ $((INSTALL))/var/log]:
-    run_user [www-data]:    #user used to run server and write log
-    run_group [www-data]:
+    logs_directory [$((INSTALL))/var/log]:
+    run_user [www-data]:      # user used to run server and write logs
+    run_group [www-data]:     # group used to run server and write logs
     Select beaker_backend:
         1 - redis
         2 - memcached
@@ -192,7 +182,7 @@
     Choose from 1, 2, 3 [1]:
     db_host [127.0.0.1]:
     db_port [8100]:
-    db_name [pyams]: zeo_pyams  # db_name created step 1
+    db_name [pyams]: zeo_pyams  # db_name created in step 1
     db_username []:
     db_password []:
     zeo_realm [pyams]:
@@ -225,7 +215,7 @@
     - python3.5 bootstrap.py
     - ./bin/buildout
 
-In the project *pyams* folder, execute *bootstrap.py*...
+In the project's *pyams* folder, execute *bootstrap.py*:
 
 .. code-block:: bash
 
@@ -235,7 +225,7 @@
     Creating directory '/var/local/env/pyams/develop-eggs'.
     Generated script '/var/local/env/pyams/bin/buildout'.
 
-...and then run *buildout*
+And run final *buildout*:
 
 .. code-block:: bash
 
@@ -243,6 +233,7 @@
 
 
 .. note::
+
     Packages download, compilation and installation can easily take several minutes. Install errors are generally due to
     missing libraries development headers.
 
@@ -267,15 +258,18 @@
     Serving on http://0.0.0.0:6543
 
 
-Congrats PyAMS is running !
+Congrats: PyAMS is running !
 
 Launch a browser and open URL http://127.0.0.1:6543/admin to get access to PyAMS management interface.
 
 
-.. warning:: By default:
+.. warning::
+
+    By default:
 
     - Login: admin
+
     - Password: admin
 
-    You must change it as soon as possible!
+    **You must change it as soon as possible!**