Major documentation update

CONTRIBUTING.rst

@@ -1,16 +1,5 @@
-If you would like to contribute to the development of OpenStack,
+If you would like to contribute to the development of this project.
-you must follow the steps in this page:
 
-   http://docs.openstack.org/infra/manual/developers.html
+Submit your pull request and issues to https://github.com/uggla/python-redfish .
 
-Once those steps have been completed, changes to OpenStack
+You can also share and discuss on the mailing list as well.
-should be submitted for review via the Gerrit tool, following
-the workflow documented at:
-
-   http://docs.openstack.org/infra/manual/developers.html#development-workflow
-
-Pull requests submitted through GitHub will be ignored.
-
-Bugs should be filed on Launchpad, not GitHub:
-
-   https://bugs.launchpad.net/python-redfish

README.rst

@@ -41,23 +41,38 @@ are discouraged due to security.
 Python requirements are listed in requirements.txt; additional requirements for
 running the unit test suite are listed in test-requirements.txt.
 
-Developer setup
+Get the sources
 ---------------
 
-To initialize a local development environment (eg, so you can run unit tests)
+The sources are available on github and can be retrieve using::
-you should run the following commands
+
+    git clone https://github.com/uggla/python-redfish
+
+As python redefish is currently in heavy development we recommend to checkout the devel branch using::
+
+    cd python-redfish
+    git checkout devel
+
+Installation
+------------
+
+Please refer to the following link.
+
+http://pythonhosted.org/python-redfish/installation.html
 
 Contacts
 --------
 
-Distribution list : python-redfish@mondorescue.org
+Distribution list: python-redfish@mondorescue.org
 
 Further References
 ------------------
 
+The specification can be found here :
+ http://www.dmtf.org/sites/default/files/standards/documents/DSP0266_1.0.1.pdf
+
 The data model documentation can be found here:
-  http://www.redfishspecification.org/redfish-data-model-and-schema/
+ http://redfish.dmtf.org/schemas/
 
 The overall protocol documentation can be found here:
-  http://www.redfishspecification.org/
+ http://www.dmtf.org/standards/redfish
-

doc/source/develsetup.rst

@@ -0,0 +1,8 @@
+===============
+Developer setup
+===============
+
+#. Follow `get the sources <http://pythonhosted.org/python-redfish/readme.html#get-the-sources>`_ section to retrieve the sources.
+#. Follow `using pip and virtualenv <http://pythonhosted.org/python-redfish/installation.html#using-pip-and-virtualenv>`_ section to create your environment.
+
+You can start hacking the code now.

doc/source/help.rst

@@ -0,0 +1,12 @@
+=============
+Help required
+=============
+
+We need help on the following topic:
+
+- debian/ubuntu dependencies packaging.
+- python3 testing.
+- installation on distributions which are not Fedora or Mageia.
+- documentation.
+
+Any contribution will be welcomed.

doc/source/index.rst

@@ -14,8 +14,10 @@ Contents:
    readme
    installation
    usage
-   contributing
+   develsetup
    classesdoc
+   contributing
+   help
 
 Indices and tables
 ==================

doc/source/installation.rst

@@ -2,11 +2,222 @@
 Installation
 ============
 
-At the command line::
+Using pip
+---------
+Use::
 
-    $ pip install python-redfish
+    sudo pip install python-redfish
 
-Or, if you have virtualenvwrapper installed::
+Pip will install :
+
+1. The library and all dependencies into your site-packages directory
+2. Redfish client master conf file into /etc/redfish_client.conf
+3. Data file (templates) into /usr/share/redfish-client/templates
+
+Point 2 and 3 above need root access to your system. If you don't have root
+access on your system, please follow `Using pip and virtualenv`_ section.
+
+
+Using pip and virtualenv
+------------------------
+
+1. Install virtualenv and virtualenvwrapper:
+
+ Fedora 22::
+
+    dnf install python-virtualenv.noarch python-virtualenvwrapper.noarch
+
+ Ubuntu 15.04::
+
+    apt-get install python-virtualenv virtualenvwrapper
+
+2. Source virtualenvwrapper.sh::
+
+    . /usr/bin/virtualenvwrapper.sh
+
+ or::
+
+    . /usr/share/virtualenvwrapper/virtualenvwrapper.sh
+
+3. Create a redfish virtual environement::
+
+    mkvirtualenv redfish
+
+4. Install using pip::
+
+    pip install python-virtualenv
+
+ All files are installed under your virtualenv.
+
+Using the sources
+-----------------
+
+#. Follow `get the sources <http://pythonhosted.org/python-redfish/readme.html#get-the-sources>`_ section to retrieve the sources.
+#. Install from the source using::
+
+    python setup.py install
+
+
+Using rpm package
+-----------------
+
+There is currently no oficial packages for distributions.
+However part of the sources there is a mechanism to buil rpm or deb packages for distributions.
+
+The mechanism is based on `project builder <http://www.project-builder.org/>`_ tool.
+
+#. Follow `get the sources <http://pythonhosted.org/python-redfish/readme.html#get-the-sources>`_ section to retrieve the sources.
+#. Download project builder for your distribution from ftp://ftp.project-builder.org.
+#. Clone the project to your own github account.
+#. Create a .pbrc with the following containt::
+
+    [uggla@ugglalaptop ~]$ cat .pbrc
+    pbdefdir python-redfish = $ENV{'HOME'}/workspace
+    pbconfdir python-redfish = $ENV{'HOME'}/workspace/python-redfish/pbconf
+    pbconfurl python-redfish = git+ssh://git@github.com:uggla/python-redfish.git
+    pburl python-redfish = git+ssh://git@github.com:uggla/python-redfish.git
+#. Build the project::
+
+    pb -p python-redfish sbx2pkg
+
+#. All packages (srpm/rpm) should be available into the build directory, then install the package using rpm::
+
+    rpm -Uvh python-redfish/build/RPMS/python-redfish-devel20160213182552.rpm
+
+
+#. Follow `get the sources <http://pythonhosted.org/python-redfish/readme.html#get-the-sources>`_ section to retrieve the sources.
+
+Using deb package
+-----------------
+
+This installation in yet possible due to missing deb package dependencies. We are working on it.
+
+In the meantime we recommend to use `Using pip`_ or `Using pip and virtualenv`_.
+
+=====================================
+Host configuration file configuration
+=====================================
+
+#. Verify redfish-client is working correclty::
+
+    redfish-client.py -h
+
+#. Create a default entry to use the mockup::
+
+    redfish-client.py config add default default http://localhost:8000/redfish/v1
+
+#. Verify the entry is correctly registered::
+
+    redfish-client.py config showall
+
+===================
+Mockup installation
+===================
+
+#. Follow `get the sources <http://pythonhosted.org/python-redfish/readme.html#get-the-sources>`_ section to retrieve the sources.
+#. Install docker using your distribution packages or the docker `procedure <https://docs.docker.com/engine/installation/>`_ (docker provide more recent packages for ubuntu)::
+
+    dnf install docker
+    systemctl enable docker.service
+    systemctl start docker.service
+    systemctl status docker.service
+
+#. Jump into the dmtf directory.
+#. Run ./buildImage.sh and ./run-redfish-simulator.sh
+#. Check that a container is running and listening on port 8000::
+
+    (pypi)[uggla@ugglalaptop dmtf]$ docker ps
+    CONTAINER ID        IMAGE                      COMMAND                  CREATED             STATUS              PORTS                  NAMES
+    9943ff1d4d93        redfish-simulator:latest   "/bin/sh -c /tmp/redf"   3 weeks ago         Up 2 days           0.0.0.0:8000->80/tcp   redfish-simulator
+#. Try to connect using a navigator to http://localhost:8000 the following screen should apear.
+
+   .. image:: images/simulator.jpg
+
+Note : in the above screenshot, firefox JSON-handle extension is used. If you want the same presentation install the extension and refresh the page.
+
+==========================
+Testing against the mockup
+==========================
+
+#. Follow `Host configuration file configuration`_ and `Mockup installation`_ section.
+#. Run the following command::
+
+    redfish-client.py manager getinfo
+
+The result should be like this::
+
+    (pypi)[uggla@ugglalaptop dmtf]$ redfish-client.py manager getinfo
+    Gathering data from manager, please wait...
+
+    Redfish API version :  1.00
+    Root Service
+
+    Managers information :
+    ======================
+
+    Manager id 1:
+    UUID : 00000000-0000-0000-0000-000000000000
+    Type : BMC
+    Firmware version : 1.00
+    State : Enabled
+    Ethernet Interface :
+        This manager has no ethernet interface
+    Managed Chassis :
+        1
+    Managed System :
+        1
+    ----------------------------
+
+    Manager id 2:
+    UUID : 00000000-0000-0000-0000-000000000000
+    Type : EnclosureManager
+    Firmware version : Not available
+    State : Enabled
+    Ethernet Interface :
+        This manager has no ethernet interface
+    Managed Chassis :
+        Enc1
+    Managed System :
+        2
+    ----------------------------
+
+    Manager id 3:
+    UUID : 00000000-0000-0000-0000-000000000000
+    Type : EnclosureManager
+    Firmware version : Not available
+    State : Enabled
+    Ethernet Interface :
+        This manager has no ethernet interface
+    Managed Chassis :
+        Enc1
+    Managed System :
+        2
+    ----------------------------
+
+
+
+============================
+Building local documentation
+============================
+
+Building the html documentation locally
+
+
+#. Follow `get the sources <http://pythonhosted.org/python-redfish/readme.html#get-the-sources>`_ section to retrieve the sources.
+#. Jump in the doc directory::
+
+    cd doc
+#. Build the html documentation::
+
+    make html
+
+
+If you want to build the documentation in pdf.
+
+#. Get texlive full distribution, ex on Fedora::
+
+    dnf install texlive-scheme-full.noarch
+#. Build the documentation::
+
+    make latexpdf
 
-    $ mkvirtualenv python-redfish
-    $ pip install python-redfish

doc/source/usage.rst

@@ -2,6 +2,25 @@
 Usage
 ========
 
-To use python-redfish in a project::
+Example using the mockup
+------------------------
+
+example/simple-simulator.py provide a simple library usage to interact with the
+redfish mockup.
+
+Example using a proliant
+------------------------
+
+example/simple-proliant.py provide a simple library usage to interact with a HP
+proliant BL460C G9 server. However this example should work on any server supplier following redfish
+standard. 
+
+refish-client usage
+-------------------
+
+The clint usage can be display using::
+
+    redfish-client.py -h
+
+This is also available at http://pythonhosted.org/python-redfish/redfish-client.html .
 
-    import redfish

examples/redfish.conf

@@ -1,5 +1,5 @@
 {
-  "Nodes": {
+  "Managers": {
     "default": {
       "url": "",
       "login": "",

examples/walk-chassis.py

@@ -1,58 +0,0 @@
-#!/usr/bin/env python
-
-#import logging
-import sys
-#from oslo_config import cfg
-#from oslo_log import log as logging
-
-import redfish
-
-# Sets up basic logging for this module
-#log_root = logging.getLogger('redfish')
-#log_root.addHandler(logging.StreamHandler(sys.stdout))
-#log_root.setLevel(logging.DEBUG)
-
-#CONF = cfg.CONF
-#logging.set_defaults(['redfish=DEBUG'])
-#logging.register_options(CONF)
-#logging.setup(CONF, "redfish")
-
-# Connect to a redfish API endpoint
-host = 'http://localhost'
-user_name = ''
-password = ''
-
-# This returns a RedfishConnection object, which implements
-# the low-level HTTP methods like GET, PUT, etc
-connection = redfish.server.connect(host, user_name, password)
-
-# From this connection, we can get the Root resource.
-# Note that the root resource is somewhat special - you create it from
-# the connection, but you create other resources from the root resource.
-# (You don't strictly have to do this, but it's simpler.)
-root = connection.get_root()
-
-print("\n")
-print("ROOT CONTROLLER")
-print("===============")
-print(root)
-
-
-# The Root class has well-defined top-level resources, such as
-# chassis, systems, managers, sessions, etc...
-chassis = root.get_chassis()
-
-print("\n")
-print("CHASSIS DATA")
-print("============")
-print(chassis)
-print("\n")
-print("WALKING CHASSIS")
-print("\n")
-print("CHASSIS contains %d items" % len(chassis))
-print("\n")
-for item in chassis:
-    print("SYSTEM")
-    print("======")
-    print(item)
-    print("\n")