--- 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!**