Improvements in documentation

- Autodescribing main modules
- More details in HOWTO to add a new service
- Basic description of CLI commands

Change-Id: I00d6c294b1008a4ebb6ed4057e8317f3de99dee0

doc/source/chronos.rst

@@ -0,0 +1,6 @@
+--------------
+Chronos client
+--------------
+
+.. automodule:: kolla_mesos.chronos
+   :members:

doc/source/deploy.rst

@@ -0,0 +1,5 @@
+--------------
+Deploy command
+--------------
+
+.. automodule:: kolla_mesos.cmd.deploy

doc/source/howto_add_a_new_service.rst

@@ -39,18 +39,57 @@ kolla-mesos-deploy to better understand the flow of operation.
 3. parse the marathon and chronos files and deploy them.
 
 
-Porting a service from kolla-ansible
-------------------------------------
+The defaults/main.yml file
+--------------------------
 
-Let's assume that kolla-ansible has the service that you want
-supported in kolla-mesos.
+This file keeps the basic variables which will be used when generating the
+other files. Of course it can re-use wariables from *config/all.yml* file
+which stores global variables for the whole kolla-mesos project.
 
-initial copying::
+We usually store the following information in this kind of files:
 
-  cp ansible/<project>/templates/* ../kolla-mesos/config/<project>/templates/
-  cp ansible/<project>/roles/config.yml ../kolla-mesos/config/<project>/<service>_config.yml
-  # then edit the above to the new format.
-  cp ansible/<projects>/defaults/main.yml ../kolla-mesos/config/<project>/defaults/main.yml
+* database name, user and address
+* Docker image name and tag
+* OpenStack credentials and options
+
+An example:
+
+.. code-block:: yaml
+
+  project_name: "keystone"
+
+  keystone_database_name: "keystone"
+  keystone_database_user: "keystone"
+  keystone_database_address: "{{ kolla_internal_address }}
+
+  keystone_image: "{{ docker_registry ~ '/' if docker_registry else '' }}{{ docker_namespace }}/{{ kolla_base_distro }}-{{ kolla_install_type }}-keystone"
+  keystone_tag: "{{ openstack_release }}"
+
+  keystone_public_address: "{{ kolla_external_address }}"
+  keystone_admin_address: "{{ kolla_internal_address }}"
+  keystone_internal_address: "{{ kolla_internal_address }}"
+
+  keystone_logging_verbose: "{{ openstack_logging_verbose }}"
+  keystone_logging_debug: "{{ openstack_logging_debug }}"
+
+
+<service>/templates/* files
+---------------------------
+
+kolla-mesos uses these files to generate the configuration of OpenStack
+services. You can use jinja2 variables here. Generally, such a config file
+should follow the practices used for creating usual config files.
+
+An example::
+
+  [DEFAULT]
+  verbose = {{ keystone_logging_verbose }}
+  debug = {{ keystone_logging_debug}}
+
+  admin_token = {{ keystone_admin_token }}
+
+  [database]
+  connection = mysql://{{ keystone_database_user }}:{{ keystone_database_password }}@{{ keystone_database_address }}/{{ keystone_database_name }}
 
 
 The <service>_config.yml file
@@ -61,6 +100,7 @@ zookeeper from the kolla-mesos repo. Note the config it's self is
 copied into zookeeper so that the container can read it too.
 
 kolla_mesos_start.py (within the running container) uses this config to:
+
 1. know where these files are placed within the container.
 2. run commands defined in the config
 
@@ -92,6 +132,7 @@ The following is an example of a config with all options used.
           requires: [/kolla/variables/project_a_bootstrap/.done]
 
 Notes on the above config.
+
 1. In the config section, "source" is the source in the kolla-mesos
    source tree and "dest" is the destination in the container. The
    contents of the file will be placed in zookeeper in the node named:
@@ -105,3 +146,17 @@ Notes on the above config.
    if it is provided. Command marked with "run_once" will not run
    on more than one node (if the "register" node exists, the command
    will be skipped).
+
+
+Porting a service from kolla-ansible
+------------------------------------
+
+Let's assume that kolla-ansible has the service that you want
+supported in kolla-mesos.
+
+initial copying::
+
+  cp ansible/<project>/templates/* ../kolla-mesos/config/<project>/templates/
+  cp ansible/<project>/roles/config.yml ../kolla-mesos/config/<project>/<service>_config.yml
+  # then edit the above to the new format.
+  cp ansible/<projects>/defaults/main.yml ../kolla-mesos/config/<project>/defaults/main.yml

doc/source/index.rst

@@ -36,9 +36,20 @@ Contents:
 .. toctree::
    :maxdepth: 1
 
-    quickstart
-    contributing
-    howto_add_new_service
+   quickstart
+   contributing
+   howto_add_a_new_service
+   man/index
+
+Code documentation
+==================
+
+.. toctree::
+   :maxdepth: 1
+
+   deploy
+   chronos
+   marathon
 
 Indices and tables
 ==================

doc/source/man/index.rst

@@ -0,0 +1,10 @@
+-----------------------
+Man pages for utilities
+-----------------------
+
+.. toctree::
+   :maxdepth: 2
+
+   kolla-mesos-deploy
+   kolla-mesos-config
+   kolla-mesos-cleanup

doc/source/man/kolla-mesos-cleanup.rst

@@ -0,0 +1,17 @@
+===================
+kolla-mesos-cleanup
+===================
+
+.. program:: kolla-mesos-cleanup
+
+SYNOPSIS
+========
+
+DESCRIPTION
+===========
+
+INVENTORY
+=========
+
+OPTIONS
+=======

doc/source/man/kolla-mesos-config.rst

@@ -0,0 +1,61 @@
+==================
+kolla-mesos-config
+==================
+
+.. program:: kolla-mesos-config
+
+SYNOPSIS
+========
+
+DESCRIPTION
+===========
+
+INVENTORY
+=========
+
+OPTIONS
+=======
+
+.. cmdoption:: --config-dir DIR
+
+  Path to a config directory to pull .conf files from. This file set is sorted,
+  so as to provide a predictable parse order if individual options are
+  over-ridden. The set is parsed after the file(s) specified via previous
+  --config-file, arguments hence over-ridden options in the directory take precedence.
+
+.. cmdoption:: --config-file PATH
+
+  Path to a config file to use. Multiple config files can be specified, with
+  values in later files taking precedence. The default files used are: None.
+
+.. cmdoption:: --noshow
+
+  The inverse of --show
+
+.. cmdoption:: --path PATH
+
+.. cmdoption:: --show
+
+.. cmdoption:: --version
+
+  show program's version number and exit
+
+.. cmdoption:: --zookeeper-host ZOOKEEPER_HOST
+
+  ZooKeeper connection URL (host:port)
+
+.. cmdoption:: --network-ipv6
+
+  Use IPv6 protocol
+
+.. cmdoption:: --network-noipv6
+
+  The inverse of --ipv6
+
+.. cmdoption:: --network-private-interface NETWORK_PRIVATE_INTERFACE
+
+  NIC connected to the private network
+
+.. cmdoption:: --network-public-interface NETWORK_PUBLIC_INTERFACE
+
+  NIC connected to the public network

doc/source/man/kolla-mesos-deploy.rst

@@ -0,0 +1,121 @@
+==================
+kolla-mesos-deploy
+==================
+
+.. program:: kolla-mesos-deploy
+
+SYNOPSIS
+========
+``kolla-mesos-deploy [options]``
+
+DESCRIPTION
+===========
+kolla-mesos-deploy runs kolla containers on Mesos (Marathon+Chronos) cluster.
+
+INVENTORY
+=========
+kolla-mesos-deploy saves configuration files for each OpenStack service on
+ZooKeeper and uses HTTP requests to call Marathon and Chronos API.
+
+OPTIONS
+=======
+
+.. cmdoption:: --config-dir DIR
+
+  Path to a config directory to pull .conf files from. This file set is
+  sorted, so as to provide a predictable parse order if individual options are
+  over-ridden. The set is parsed after the file(s) specified via previous
+  --config-file, arguments hence over-ridden options in the directory take
+  precedence.
+
+.. cmdoption:: --config-file PATH
+
+  Path to a config file to use. Multiple config files can be specified, with
+  values in later files taking precedence. The default files used are: None.
+
+.. cmdoption:: --force
+
+.. cmdoption:: --noforce
+
+  The inverse of --force
+
+.. cmdoption:: --noupdate
+
+  The inverse of --update
+
+.. cmdoption:: --update
+
+.. cmdoption:: --version
+
+  show program's version number and exit
+
+  --profiles-aux PROFILES_AUX
+  --profiles-default PROFILES_DEFAULT
+  --profiles-gate PROFILES_GATE
+  --profiles-infra PROFILES_INFRA
+  --profiles-main PROFILES_MAIN
+
+.. cmdoption:: --kolla-base KOLLA_BASE
+
+  The base distro which was used to build images
+
+.. cmdoption:: --kolla-base-tag KOLLA_BASE_TAG
+
+  The base distro image tag
+
+.. cmdoption:: --kolla-install-type KOLLA_INSTALL_TYPE
+
+  The method of the OpenStack install
+
+.. cmdoption:: --kolla-namespace KOLLA_NAMESPACE
+
+  The Docker namespace name
+
+.. cmdoption:: --kolla-profile KOLLA_PROFILE
+
+  Build profile which was used to build images
+
+.. cmdoption:: --kolla-tag KOLLA_TAG
+
+  The Docker tag
+
+.. cmdoption:: --marathon-host MARATHON_HOST
+
+  Marathon connection URL (http://host:port)
+
+.. cmdoption:: --marathon-timeout MARATHON_TIMEOUT
+
+  Timeout for the request to the Marathon API
+
+.. cmdoption:: --zookeeper-host ZOOKEEPER_HOST
+
+  ZooKeeper connection URL (host:port)
+
+.. cmdoption:: --chronos-host CHRONOS_HOST
+
+  Chronos connection URL (http://host:port)
+
+.. cmdoption:: --chronos-timeout CHRONOS_TIMEOUT
+
+  Timeout for the request to the Chronos API
+
+.. cmdoption:: --network-ipv6
+
+  Use IPv6 protocol
+
+.. cmdoption:: --network-noipv6
+
+  The inverse of --ipv6
+
+.. cmdoption:: --network-private-interface NETWORK_PRIVATE_INTERFACE
+
+  NIC connected to the private network
+
+.. cmdoption:: --network-public-interface NETWORK_PUBLIC_INTERFACE
+
+  NIC connected to the public network
+
+FILES
+=====
+
+* /etc/kolla-mesos/kolla-mesos.conf

doc/source/marathon.rst

@@ -0,0 +1,6 @@
+---------------
+Marathon client
+---------------
+
+.. automodule:: kolla_mesos.marathon
+   :members:

kolla_mesos/common/file_utils.py

@@ -48,11 +48,14 @@ def get_src_dir():
 
 def find_base_dir():
     script_path = os.path.dirname(os.path.realpath(sys.argv[0]))
-    if os.path.basename(script_path) == 'cmd':
+    base_script_path = os.path.basename(script_path)
+    if base_script_path == 'kolla-mesos':
+        return script_path
+    if base_script_path == 'cmd':
         return os.path.join(script_path, '..', '..')
-    if os.path.basename(script_path) == 'subunit':
+    if base_script_path == 'subunit':
         return get_src_dir()
-    if os.path.basename(script_path) == 'bin':
+    if base_script_path == 'bin':
         base_dir = '/usr/share/kolla-mesos'
         if os.path.exists(base_dir):
             return base_dir