[pytango] 89/98: Update documentation (PR #46)
Sandor Bodo-Merle
sbodomerle-guest at moszumanska.debian.org
Thu Sep 28 19:17:48 UTC 2017
This is an automated email from the git hooks/post-receive script.
sbodomerle-guest pushed a commit to tag v9.2.0
in repository pytango.
commit 4e32a03fe636770d4305ed6d095e376b4e2d0964
Author: AntoineDupre <dupre.antoine.nicolas at gmail.com>
Date: Wed Aug 17 14:18:35 2016 +0200
Update documentation (PR #46)
* Update rpm location and compiling section.
* Link side bar to readthedocs links
* Update dead url and readthedocs url
* Cleaning outdated questions
* remove 'index.html' from documentation url
* Add 'how to contribuate' in faq section
---
README.rst | 12 ++-
doc/_templates/indexsidebar.html | 6 +-
doc/faq.rst | 221 +--------------------------------------
doc/start.rst | 24 ++---
4 files changed, 25 insertions(+), 238 deletions(-)
diff --git a/README.rst b/README.rst
index ef6846b..fd5d05b 100644
--- a/README.rst
+++ b/README.rst
@@ -52,7 +52,7 @@ PyTango_ is available on PyPI_ as ``pytango``::
$ pip install pytango
Alternatively, PyTango_ can be built and installed from the
-`sources <PyTango_>`__::
+`sources`_::
$ python setup.py install
@@ -75,7 +75,7 @@ For an interactive use, consider using ITango_, a tango IPython_ profile.
Documentation
-------------
-Check out the `documentation <Documentation_>`__ for more informations.
+Check out the documentation_ for more informations.
@@ -84,7 +84,7 @@ Support and contribution
You can get support from the `Tango forums`_, for both Tango_ and PyTango_ questions.
-All contributions, `PR and bug reports <PyTango_>`__ are welcome!
+All contributions, `PR and bug reports`_ are welcome!
.. _Tango: http://tango-controls.org/
@@ -104,5 +104,7 @@ All contributions, `PR and bug reports <PyTango_>`__ are welcome!
.. _ITango: http://pypi.python.org/pypi/itango
.. _IPython: http://ipython.org
-.. _Documentation: http://esrf.eu/computing/cs/tango/tango_doc/kernel_doc/pytango
-.. _Tango forums: http://tango-controls.org/community/forums
+.. _documentation: http://pytango.readthedocs.io/en/latestl
+.. _Tango forums: http://tango-controls.org/community/forum
+.. _PR and bug reports: PyTango_
+.. _sources: PyTango_
diff --git a/doc/_templates/indexsidebar.html b/doc/_templates/indexsidebar.html
index 25d2e8a..e0c00a7 100644
--- a/doc/_templates/indexsidebar.html
+++ b/doc/_templates/indexsidebar.html
@@ -5,13 +5,13 @@ or install it with:</p>
<pre>pip install PyTango</pre>
<h3>PDF</h3>
-<p>A PDF version <a href="PyTango.pdf">here</a>.
+<p>A PDF version <a href="https://media.readthedocs.org/pdf/pytango/latest/pytango.pdf">here</a>.
<h3>Other versions</h3>
-<a href="http://www.esrf.eu/computing/cs/tango/pytango/development/index.html">Development</a>
+<a href="http://pytango.readthedocs.io/en/latest">Development</a>
<br/>
-<a href="http://www.esrf.eu/computing/cs/tango/pytango/latest/index.html">Latest stable</a>
+<a href="http://pytango.readthedocs.io/en/stable">Latest stable</a>
<br/>
<a href="http://www.esrf.eu/computing/cs/tango/pytango/v818/index.html">8.1.8</a>
<br/>
diff --git a/doc/faq.rst b/doc/faq.rst
index 787b3d9..012b874 100644
--- a/doc/faq.rst
+++ b/doc/faq.rst
@@ -8,18 +8,10 @@ FAQ
Answers to general Tango questions can be found in the
`general tango tutorial <http://www.tango-controls.org/resources/tutorials>`_.
-Please also check the `general tango how to <http://www.tango-controls.org/resources/howto>`_.
+Please also check the `general tango how to <http://www.tango-controls.org/resources/howto/>`_.
-**Where are the usual bjam files?**
-
-Starting from PyTango 7.0.0 the prefered way to build PyTango is using the standard
-python distutils package. This means that:
-
-- you do NOT have to install the additional bjam package
-- you do NOT have to change 3 configuration files
-- you do NOT need to have 2Gb of RAM to compile PyTango.
-
-Please check the compilation chapter for details on how to build PyTango.
+**How can I contribute to pytango and documentation ?**
+You can open pull requests on `PyTango github page <https://github.com/tango-cs/pytango/pulls>`_.
**I got a libbost_python error when I try to import PyTango module**
@@ -49,210 +41,3 @@ To see which boost python file PyTango needs type::
/lib64/ld-linux-x86-64.so.2 (0x00007f3940a4c000)
-**My python code uses PyTango 3.0.4 API. How do I change to 7.0.0 API?**
-
-To ease migration effort, PyTango 7 provides an alternative module called
-PyTango3.
-
-Changing your python import from::
-
- import PyTango
-
-to::
-
- import PyTango3 as PyTango
-
-should allow you to execute your old PyTango code using the new PyTango 7 library.
-
-Please note that you should as soon as possible migrate the code to Tango 7
-since the PyTango team cannot assure the maintainability of the PyTango3 module.
-
-Please find below a basic set of rules to migrate from PyTango 3.0.x to 7:
-
-*General rule of thumb for data types*
-
-The first important thing to be aware of when migrating from PyTango <= 3.0.4 to
-PyTango >= 7 is that the data type mapping from tango to python and vice versa is
-not always the same. The following table summarizes the differences:
-
-+-------------------------+-------------------------------------------+-------------------------------------------+
-| Tango data type | PyTango 7 type | PyTango <= 3.0.4 type |
-+=========================+===========================================+===========================================+
-| DEV_VOID | No data | No data |
-+-------------------------+-------------------------------------------+-------------------------------------------+
-| DEV_BOOLEAN | bool | bool |
-+-------------------------+-------------------------------------------+-------------------------------------------+
-| DEV_SHORT | int | int |
-+-------------------------+-------------------------------------------+-------------------------------------------+
-| DEV_LONG | int | int |
-+-------------------------+-------------------------------------------+-------------------------------------------+
-| DEV_LONG64 | long (on a 32 bits computer) or | long (on a 32 bits computer) or |
-| | int (on a 64 bits computer) | int (on a 64 bits computer) |
-+-------------------------+-------------------------------------------+-------------------------------------------+
-| DEV_FLOAT | float | float |
-+-------------------------+-------------------------------------------+-------------------------------------------+
-| DEV_DOUBLE | float | float |
-+-------------------------+-------------------------------------------+-------------------------------------------+
-| DEV_USHORT | int | int |
-+-------------------------+-------------------------------------------+-------------------------------------------+
-| DEV_ULONG | int | int |
-+-------------------------+-------------------------------------------+-------------------------------------------+
-| DEV_ULONG64 | long (on a 32 bits computer) or | long (on a 32 bits computer) or |
-| | int (on a 64 bits computer) | int (on a 64 bits computer) |
-+-------------------------+-------------------------------------------+-------------------------------------------+
-| DEV_STRING | str | str |
-+-------------------------+-------------------------------------------+-------------------------------------------+
-| DEVVAR_CHARARRAY | sequence<int> | list<int> |
-+-------------------------+-------------------------------------------+-------------------------------------------+
-| DEVVAR_SHORTARRAY | sequence<int> | list<int> |
-+-------------------------+-------------------------------------------+-------------------------------------------+
-| DEVVAR_LONGARRAY | sequence<int> | list<int> |
-+-------------------------+-------------------------------------------+-------------------------------------------+
-| DEVVAR_LONG64ARRAY | sequence<long> (on a 32 bits computer) or | list<long> (on a 32 bits computer) or |
-| | sequence<int> (on a 64 bits computer) | list<int> (on a 64 bits computer) |
-+-------------------------+-------------------------------------------+-------------------------------------------+
-| DEVVAR_FLOATARRAY | sequence<float> | list<float> |
-+-------------------------+-------------------------------------------+-------------------------------------------+
-| DEVVAR_DOUBLEARRAY | sequence<float> | list<float> |
-+-------------------------+-------------------------------------------+-------------------------------------------+
-| DEVVAR_USHORTARRAY | sequence<int> | list<int> |
-+-------------------------+-------------------------------------------+-------------------------------------------+
-| DEVVAR_ULONGARRAY | sequence<int> | list<int> |
-+-------------------------+-------------------------------------------+-------------------------------------------+
-| DEVVAR_ULONG64ARRAY | sequence<long> (on a 32 bits computer) or | list<long> (on a 32 bits computer) or |
-| | sequence<int> (on a 64 bits computer) | list<int> (on a 64 bits computer) |
-+-------------------------+-------------------------------------------+-------------------------------------------+
-| DEVVAR_STRINGARRAY | sequence<str> | list<str> |
-+-------------------------+-------------------------------------------+-------------------------------------------+
-| | A sequence with two elements: | A list with two elements: |
-| DEVVAR_LONGSTRINGARRAY | 1. sequence<int> | 1. list<int> |
-| | 2. sequence<str> | 2. list<str> |
-+-------------------------+-------------------------------------------+-------------------------------------------+
-| | A sequence with two elements: | A list with two elements: |
-|DEVVAR_DOUBLESTRINGARRAY | 1. sequence<float> | 1. list<float> |
-| | 2. sequence<str> | 2. list<str> |
-+-------------------------+-------------------------------------------+-------------------------------------------+
-
-Note that starting from PyTango 7 you **cannot assume anything** about the concrete
-sequence implementation for the tango array types in PyTango.
-This means that the following code (valid in PyTango <= 3.0.4)::
-
- import PyTango
- dp = PyTango.DeviceProxy("my/device/experiment")
- da = dp.read_attribute("array_attr")
- if isinstance(da.value, list):
- print "array_attr is NOT a scalar attribute"
-
-must be replaced with::
-
- import operator, types
- import PyTango
- dp = PyTango.DeviceProxy("my/device/experiment")
- da = dp.read_attribute("array_attr")
- if operator.isSequence(da.value) and not type(da.value) in types.StringTypes:
- print "array_attr is NOT a scalar attribute"
-
-Note that the above example is intended for demonstration purposes only. For
-reference, the proper code would be::
-
- import PyTango
- dp = PyTango.DeviceProxy("my/device/experiment")
- da = dp.read_attribute("array_attr")
- if not da.data_format is PyTango.AttrDataFormat.SCALAR:
- print "array_attr is NOT a scalar attribute"
-
-*Server*
-
-
-#. replace `PyTango.PyUtil` with :class:`Util`
-
-#. replace `PyTango.PyDeviceClass` with :class:`DeviceClass`
-
-#. state and status overwrite
- in PyTango <= 3.0.4, in order to overwrite the default state and status in a device
- server, you had to reimplement **State()** and **Status()** methods respectively.
-
- in PyTango 7 the methods have been renamed to **dev_state()** and **dev_status()** in
- order to match the C++ API.
-
-*General*
-
-#. AttributeValue does **NOT** exist anymore.
- - the result of a read_attribute call on a :class:`DeviceProxy` / :class:`Group`
- is now a :class:`DeviceAttribute` object
- - write_attribute does not accept AttributeValue anymore
-
- (See :class:`DeviceProxy` API documentation for more details)
-
-#. command_inout for commands with parameter type DevVar****StringArray don't accept items in second sequence not being strings:
- For example, a tango command 'DevVoid Go(DevVarDoubleArray)' in tango 3.0.4
- could be executed by calling::
-
- dev_proxy.command_inout( 'Go', [[1.0, 2.0], [1, 2, 3]] )
-
- and the second list would internally be converted to ['1', '2', '3'].
- Starting from PyTango 7 this is not allowed anymore. So the above code
- must be changed to::
-
- dev_proxy.command_inout( 'Go', [[1.0, 2.0], ['1', '2', '3']] )
-
-#. :class:`EventType` enumeration constants changed to match C++ enumeration
- - CHANGE -> CHANGE_EVENT
- - QUALITY -> QUALITY_EVENT
- - PERIODIC -> PERIODIC_EVENT
- - ARCHIVE -> ARCHIVE_EVENT
- - USER -> USER_EVENT
- - ATTR_CONF_EVENT remains
-
-#. Exception handling
- in 3.0.4 :class:`DevFailed` was a tuple of dictionaries.
- Now :class:`DevFailed` is a tuple of :class:`DevError`.
- This means that code::
-
- try:
- tango_fail()
- except PyTango.DevFailed as e:
- print e.args[0]['reason']
-
- needs to be replaced with::
-
- try:
- tango_fail()
- except PyTango.DevFailed as e:
- print e.args[0].reason
-
-
-*Optional*
-
-The following is a list of API improvements. Some where added for performance
-reasons, others to allow for a more pythonic interface, others still to reflect
-more adequately the C++ interface. They are not mandatory since the original
-interface will still be available.
-
-**Why is there a "-Wstrict-prototypes" warning when I compile PyTango?**
-
-
-The PyTango prefered build system (distutils) uses the same flags used to compile
-Python to compile PyTango. It happens that Python is compiled as a pure C library
-while PyTango is a C++ library. Unfortunately one of the flags used by Python is
-the "-Wstrict-prototypes" which makes sence in a C compilation but not in a C++
-compilation.
-For reference here is the complete error message you may have:
-
- `cc1plus: warning: command line option "-Wstrict-prototypes" is valid for Ada/C/ObjC but not for C++`
-
-Do not worry about this warning since the compiler is ignoring the presence of this flag
-in the compilation.
-
-**Why are there so many warnings when generating the documentation?**
-
-PyTango uses boost python for the binding between C++ and Python and sphinx for
-document generation.
-When sphinx generates the PyTango API documentation it uses introspection to search
-for documentation in the python code. It happens that boost overrides some python
-introspection API for functions and methods which sphinx expects to have. Therefore
-you should see many warnings of type:
-
- `(WARNING/2) error while formatting signature for PyTango.Device_4Impl.always_executed_hook: **arg is not a Python function**`
-
-Do not worry since sphinx is able to generate the proper documentation.
diff --git a/doc/start.rst b/doc/start.rst
index 2faad75..7ded997 100644
--- a/doc/start.rst
+++ b/doc/start.rst
@@ -9,6 +9,7 @@ Getting started
Installing
----------
+
Linux
~~~~~
@@ -23,10 +24,11 @@ RPM packages are also available for RHEL & CentOS:
.. hlist::
:columns: 2
- * `RHEL 5/CentOS 5 32bits <ftp://ftp.maxlab.lu.se/pub/maxlab/packages/el5/i386/repoview/index.html>`_
- * `RHEL 5/CentOS 5 64bits <ftp://ftp.maxlab.lu.se/pub/maxlab/packages/el5/x86_64/repoview/index.html>`_
- * `RHEL 6/CentOS 6 32bits <ftp://ftp.maxlab.lu.se/pub/maxlab/packages/el6/i386/repoview/index.html>`_
- * `RHEL 6/CentOS 6 64bits <ftp://ftp.maxlab.lu.se/pub/maxlab/packages/el6/x86_64/repoview/index.html>`_
+ * `CentOS 6 32bits <http://pubrepo.maxiv.lu.se/rpm/el6/x86_64/>`_
+ * `CentOS 6 64bits <http://pubrepo.maxiv.lu.se/rpm/el6/x86_64/>`_
+ * `CentOS 7 64bits <http://pubrepo.maxiv.lu.se/rpm/el7/x86_64/>`_
+ * `Fedora 23 32bits <http://pubrepo.maxiv.lu.se/rpm/fc23/i/386/>`_
+ * `Fedora 23 64bits <http://pubrepo.maxiv.lu.se/rpm/fc23/x86_64/>`_
PyPi
~~~~
@@ -38,7 +40,6 @@ are available from the major official distribution repositories):
* `boost-python`_ (including boost-python-dev)
* `numpy`_
-* `IPython`_ (optional, highly recommended)
Then install PyTango either from pip:
@@ -70,8 +71,8 @@ Compiling
Linux
~~~~~
-Since PyTango 7 the build system used to compile PyTango is the standard python
-distutils.
+Since PyTango 9 the build system used to compile PyTango is the standard python
+setuptools.
Besides the binaries for the three dependencies mentioned above, you also need
the development files for the respective libraries.
@@ -81,14 +82,13 @@ the latest SVN checkout:
.. sourcecode:: console
- $ svn co http://svn.code.sf.net/p/tango-cs/code/bindings/PyTango/trunk PyTango
- $ cd PyTango
+ $ git clone https://github.com/tango-cs/pytango.git
+ $ cd pytango
$ python setup.py build
$ sudo python setup.py install
-This will install PyTango in the system python installation directory and, since
-version 8.0.0, it will also install :ref:`itango` as an IPython_ extension.
-
+This will install PyTango in the system python installation directory.
+(Since PyTango9, :ref:`itango` has been removed to a separate project and it will not be installed with PyTango.)
If you whish to install in a different directory, replace the last line with:
.. sourcecode:: console
--
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/debian-science/packages/pytango.git
More information about the debian-science-commits
mailing list