From 094276cda77d814d07ad885e7d63de8d1243750a Mon Sep 17 00:00:00 2001 From: Ilya Etingof Date: Mon, 17 Jul 2017 13:06:03 +0200 Subject: [PATCH] rearrange existing documentation to follow the new layout Change-Id: I50774641757af1a608ebf739a7f171725bd4f9ec --- README.rst | 186 +----------------- doc/source/conf.py | 5 +- .../index.rst} | 2 +- doc/source/index.rst | 24 +-- doc/source/install/index.rst | 48 +++++ doc/source/installation.rst | 12 -- doc/source/readme.rst | 1 - doc/source/{spec.rst => reference/index.rst} | 9 +- doc/source/usage.rst | 7 - doc/source/user/index.rst | 139 +++++++++++++ releasenotes/source/conf.py | 4 +- setup.cfg | 1 + test-requirements.txt | 2 +- 13 files changed, 212 insertions(+), 228 deletions(-) rename doc/source/{contributing.rst => contributor/index.rst} (50%) create mode 100644 doc/source/install/index.rst delete mode 100644 doc/source/installation.rst delete mode 100644 doc/source/readme.rst rename doc/source/{spec.rst => reference/index.rst} (95%) delete mode 100644 doc/source/usage.rst create mode 100644 doc/source/user/index.rst diff --git a/README.rst b/README.rst index c408be4..176052d 100644 --- a/README.rst +++ b/README.rst @@ -3,185 +3,7 @@ MoltenIron overview MoltenIron maintains a pool of bare metal nodes. -Installation ------------- - -With a clean installation of an Ubuntu 16.04 system, do the following:: - - $ sudo apt-get install -y build-essential python-dev python3-dev - $ sudo apt-get install -y libmysqlclient-dev tox python2.7 python3.5 - $ sudo apt-get install -y mysql-server - -If you see:: - - E: Unable to locate package tox - -then remove tox and reinstall. Next, do the following:: - - $ sudo pip install --upgrade tox - -Then, check out the MoltenIron project:: - - $ git clone git://git.openstack.org/openstack/molteniron.git - $ cd molteniron/ - -Before you can install the package requirements, you may need to install a -prerequisite (on a non-clean system):: - - $ hash mysql_config || sudo apt install -y libmysqlclient-dev - -Then install the package requirements:: - - $ sudo pip install -U --force-reinstall -r requirements.txt - -Before starting the server for the first time, the createDB.py -script must be run as follows:: - - $ createDB.py - -Or with a clean installation of an Ubuntu 16.04 system, do the following:: - - $ sudo apt-get update - $ git clone git://git.openstack.org/openstack/molteniron.git - $ cd molteniron/ - $ ./utils/install_requirements.sh - -You can run the suite of testcases to make sure everything works:: - - $ (rm -rf .tox/py27/ testenv/; tox -epy27) - $ (rm -rf .tox/py35/ testenv/; tox -epy35) - -Starting --------- - -To start the server:: - - $ sudo moltenirond-helper start - - -To stop the server:: - - $sudo moltenirond-helper stop - - -MoltenIron client ------------------ - -Use the molteniron client (molteniron) to communicate with the server. For -usage information type:: - - $ molteniron -h - - -For usage of a specific command use:: - - $ molteniron [command] -h - - -MoltenIron commands -------------------- - -+----------+---------------------------------------------+ -|command | description | -+==========+=============================================+ -|add | Add a node | -+----------+---------------------------------------------+ -|allocate | Allocate a node | -+----------+---------------------------------------------+ -|release | Release a node | -+----------+---------------------------------------------+ -|get_field | Get a specific field in a node | -+----------+---------------------------------------------+ -|set_field | Set a specific field with a value in a node | -+----------+---------------------------------------------+ -|status | Return the status of every node | -+----------+---------------------------------------------+ -|delete_db | Delete every database entry | -+----------+---------------------------------------------+ - -Configuration of MoltenIron ---------------------------- - -Configuration of MoltenIron is specified in the file conf.yaml. - -"Both" means that this configuration option is required for both the client and -the server. "Client" means that it is required only for the client. "Server" -means it is only required for the server. - -+-------+------------+----------------------------------------------------------+ -|usage | key | description | -+=======+============+==========================================================+ -|Both | mi_port | the port that the server uses to respond to commands. | -+-------+------------+----------------------------------------------------------+ -|Client | serverIP | The IP address of the server. This is only used by | -| | | clients. | -+-------+------------+----------------------------------------------------------+ -|Server | maxTime | The maximum amount of time, in seconds, that a node | -| | | is allowed to be allocated to a particular BM node. | -+-------+------------+----------------------------------------------------------+ -|Server | logdir | The path to the directory where the logs should be | -| | | stored. | -+-------+------------+----------------------------------------------------------+ -|Server | maxLogDays | The amount of time, in days, to keep old logs. | -+-------+------------+----------------------------------------------------------+ -|Server | sqlUser | The username to use for the MI server. This user | -| | | will automatically be generated when createDB.py is run. | -+-------+------------+----------------------------------------------------------+ -|Server | sqlPass | The password of sqlUser | -+-------+------------+----------------------------------------------------------+ - -Running testcases ------------------ - -The suite of testcases is checked by tox. But, before you can run tox, you -need to change the local yaml configuration file to point to the log -directory. An example:: - - (LOG=$(pwd)/testenv/log; sed -i -r -e 's,^(logdir: )(.*)$,\1'${LOG}',' conf.yaml; rm -rf testenv/; tox -e testenv) - -Running inside a Continuous Integration environment ---------------------------------------------------- - -During the creation of a job, in the pre_test_hook.sh, add the following snippet of bash code:: - - # Setup MoltenIron and all necessary prerequisites. - # And then call the MI script to allocate a node. - ( - REPO_DIR=/opt/stack/new/molteniron - MI_CONF_DIR=/usr/local/etc/molteniron - MI_IP=10.1.2.3 # @TODO - Replace with your IP addr here! - - # Grab molteniron and install it - git clone https://git.openstack.org/openstack/molteniron ${REPO_DIR} || exit 1 - - cd ${REPO_DIR} - - # @BUG Install prerequisite before running pip to install the requisites - hash mysql_config || sudo apt install -y libmysqlclient-dev - - # Install the requisites for this package - sudo pip install --upgrade --force-reinstall --requirement requirements.txt - - # Run the python package installation program - sudo python setup.py install - - if [ -n "${MI_IP}" ] - then - # Set the molteniron server IP in the conf file - sudo sed -i "s/127.0.0.1/${MI_IP}/g" ${MI_CONF_DIR}/conf.yaml - fi - - sudo ${REPO_DIR}/utils/test_hook_mi_ipmiblob.py \ - --hardware-info=/opt/stack/new/devstack/files/hardware_info \ - --localrc=/opt/stack/new/devstack/localrc \ - ${dsvm_uuid} \ - 1 - ) || exit $? - -and change the MI_IP environment variable to be your MoltenIron server! - -During the destruction of a job, in the post_test_hook.sh, add the following snippet of bash code:: - - DSVM_UUID="$(`_. Problem description =================== diff --git a/doc/source/usage.rst b/doc/source/usage.rst deleted file mode 100644 index 2efe5b1..0000000 --- a/doc/source/usage.rst +++ /dev/null @@ -1,7 +0,0 @@ -======== -Usage -======== - -To use molteniron.git in a project:: - - import molteniron diff --git a/doc/source/user/index.rst b/doc/source/user/index.rst new file mode 100644 index 0000000..bb5a66c --- /dev/null +++ b/doc/source/user/index.rst @@ -0,0 +1,139 @@ + +Usage +===== + +Starting +-------- + +To start the server:: + + $ sudo moltenirond-helper start + + +To stop the server:: + + $sudo moltenirond-helper stop + + +MoltenIron client +----------------- + +Use the molteniron client (molteniron) to communicate with the server. For +usage information type:: + + $ molteniron -h + + +For usage of a specific command use:: + + $ molteniron [command] -h + + +MoltenIron commands +------------------- + ++----------+---------------------------------------------+ +|command | description | ++==========+=============================================+ +|add | Add a node | ++----------+---------------------------------------------+ +|allocate | Allocate a node | ++----------+---------------------------------------------+ +|release | Release a node | ++----------+---------------------------------------------+ +|get_field | Get a specific field in a node | ++----------+---------------------------------------------+ +|set_field | Set a specific field with a value in a node | ++----------+---------------------------------------------+ +|status | Return the status of every node | ++----------+---------------------------------------------+ +|delete_db | Delete every database entry | ++----------+---------------------------------------------+ + +Configuration of MoltenIron +--------------------------- + +Configuration of MoltenIron is specified in the file conf.yaml. + +"Both" means that this configuration option is required for both the client and +the server. "Client" means that it is required only for the client. "Server" +means it is only required for the server. + ++-------+------------+----------------------------------------------------------+ +|usage | key | description | ++=======+============+==========================================================+ +|Both | mi_port | the port that the server uses to respond to commands. | ++-------+------------+----------------------------------------------------------+ +|Client | serverIP | The IP address of the server. This is only used by | +| | | clients. | ++-------+------------+----------------------------------------------------------+ +|Server | maxTime | The maximum amount of time, in seconds, that a node | +| | | is allowed to be allocated to a particular BM node. | ++-------+------------+----------------------------------------------------------+ +|Server | logdir | The path to the directory where the logs should be | +| | | stored. | ++-------+------------+----------------------------------------------------------+ +|Server | maxLogDays | The amount of time, in days, to keep old logs. | ++-------+------------+----------------------------------------------------------+ +|Server | sqlUser | The username to use for the MI server. This user | +| | | will automatically be generated when createDB.py is run. | ++-------+------------+----------------------------------------------------------+ +|Server | sqlPass | The password of sqlUser | ++-------+------------+----------------------------------------------------------+ + +Running testcases +----------------- + +The suite of testcases is checked by tox. But, before you can run tox, you +need to change the local yaml configuration file to point to the log +directory. An example:: + + (LOG=$(pwd)/testenv/log; sed -i -r -e 's,^(logdir: )(.*)$,\1'${LOG}',' conf.yaml; rm -rf testenv/; tox -e testenv) + +Running inside a Continuous Integration environment +--------------------------------------------------- + +During the creation of a job, in the pre_test_hook.sh, add the following snippet of bash code:: + + # Setup MoltenIron and all necessary prerequisites. + # And then call the MI script to allocate a node. + ( + REPO_DIR=/opt/stack/new/molteniron + MI_CONF_DIR=/usr/local/etc/molteniron + MI_IP=10.1.2.3 # @TODO - Replace with your IP addr here! + + # Grab molteniron and install it + git clone https://git.openstack.org/openstack/molteniron ${REPO_DIR} || exit 1 + + cd ${REPO_DIR} + + # @BUG Install prerequisite before running pip to install the requisites + hash mysql_config || sudo apt install -y libmysqlclient-dev + + # Install the requisites for this package + sudo pip install --upgrade --force-reinstall --requirement requirements.txt + + # Run the python package installation program + sudo python setup.py install + + if [ -n "${MI_IP}" ] + then + # Set the molteniron server IP in the conf file + sudo sed -i "s/127.0.0.1/${MI_IP}/g" ${MI_CONF_DIR}/conf.yaml + fi + + sudo ${REPO_DIR}/utils/test_hook_mi_ipmiblob.py \ + --hardware-info=/opt/stack/new/devstack/files/hardware_info \ + --localrc=/opt/stack/new/devstack/localrc \ + ${dsvm_uuid} \ + 1 + ) || exit $? + +and change the MI_IP environment variable to be your MoltenIron server! + +During the destruction of a job, in the post_test_hook.sh, add the following snippet of bash code:: + + DSVM_UUID="$(=0.11.0,<0.12 # Apache-2.0 coverage>=4.0 # Apache-2.0 python-subunit>=0.0.18 # Apache-2.0/BSD sphinx>=1.2.1,!=1.3b1,<1.4 # BSD -oslosphinx>=4.7.0 # Apache-2.0 +openstackdocstheme>=1.11.0 # Apache-2.0 oslotest>=1.10.0 # Apache-2.0 testrepository>=0.0.18 # Apache-2.0/BSD testscenarios>=0.4 # Apache-2.0/BSD