diff --git a/.gitignore b/.gitignore index b384b556..195ce07e 100644 --- a/.gitignore +++ b/.gitignore @@ -6,7 +6,7 @@ # Sphinx _build -doc/source/api/ +doc/source/reference/api/ # Packages/installer info *.egg diff --git a/doc/source/contributor/index.rst b/doc/source/contributor/index.rst new file mode 100644 index 00000000..966b8279 --- /dev/null +++ b/doc/source/contributor/index.rst @@ -0,0 +1,72 @@ +====================== +Welcome to Ironic-lib! +====================== + +Overview +======== + +Ironic-lib is a library for use by projects under Bare Metal governance only. +This documentation is intended for developer use only. If you are looking for +documentation for deployers, please see the +`ironic documentation `_. + +Metrics +======= + +Ironic-lib provides a pluggable metrics library as of the 2.0.0 release. +Current provided backends are the default, 'noop', which discards all data, +and 'statsd', which emits metrics to a statsd daemon over the network. The +metrics backend to be used is configured via ``CONF.metrics.backend``. How +this configuration is set in practice may vary by project. + +The typical usage of metrics is to initialize and cache a metrics logger, +using the `get_metrics_logger()` method in `ironic_lib.metrics_utils`, then +use that object to decorate functions or create context managers to gather +metrics. The general convention is to provide the name of the module as the +first argument to set it as the prefix, then set the actual metric name to the +method name. For example: + +.. code-block:: python + + from ironic_lib import metrics_utils + + METRICS = metrics_utils.get_metrics_logger(__name__) + + @METRICS.timer('my_simple_method') + def my_simple_method(arg, matey): + pass + + def my_complex_method(arg, matey): + with METRICS.timer('complex_method_pt_1'): + do_some_work() + + with METRICS.timer('complex_method_pt_2'): + do_more_work() + +There are three different kinds of metrics: + - **Timers** measure how long the code in the decorated method or context + manager takes to execute, and emits the value as a timer metric. These + are useful for measuring performance of a given block of code. + - **Counters** increment a counter each time a decorated method or context + manager is executed. These are useful for counting the number of times a + method is called, or the number of times an event occurs. + - **Gauges** return the value of a decorated method as a metric. This is + useful when you want to monitor the value returned by a method over time. + +Additionally, metrics can be sent directly, rather than using a context +manager or decorator, when appropriate. When used in this way, ironic-lib will +simply emit the value provided as the requested metric type. For example: + +.. code-block:: python + + from ironic_lib import metrics_utils + + METRICS = metrics_utils.get_metrics_logger(__name__) + + def my_node_failure_method(node): + if node.failed: + METRICS.send_counter(node.uuid, 1) + +The provided statsd backend natively supports all three metric types. For more +information about how statsd changes behavior based on the metric type, see +`statsd metric types `_ diff --git a/doc/source/index.rst b/doc/source/index.rst index e5530bd9..f2910ff1 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -1,92 +1,17 @@ -====================== -Welcome to Ironic-lib! -====================== - -Overview -======== +======================== +Ironic-lib Documentation +======================== Ironic-lib is a library for use by projects under Bare Metal governance only. This documentation is intended for developer use only. If you are looking for documentation for deployers, please see the -`ironic documentation `_. - -Metrics -======= - -Ironic-lib provides a pluggable metrics library as of the 2.0.0 release. -Current provided backends are the default, 'noop', which discards all data, -and 'statsd', which emits metrics to a statsd daemon over the network. The -metrics backend to be used is configured via ``CONF.metrics.backend``. How -this configuration is set in practice may vary by project. - -The typical usage of metrics is to initialize and cache a metrics logger, -using the `get_metrics_logger()` method in `ironic_lib.metrics_utils`, then -use that object to decorate functions or create context managers to gather -metrics. The general convention is to provide the name of the module as the -first argument to set it as the prefix, then set the actual metric name to the -method name. For example: - -.. code-block:: python - - from ironic_lib import metrics_utils - - METRICS = metrics_utils.get_metrics_logger(__name__) - - @METRICS.timer('my_simple_method') - def my_simple_method(arg, matey): - pass - - def my_complex_method(arg, matey): - with METRICS.timer('complex_method_pt_1'): - do_some_work() - - with METRICS.timer('complex_method_pt_2'): - do_more_work() - -There are three different kinds of metrics: - - **Timers** measure how long the code in the decorated method or context - manager takes to execute, and emits the value as a timer metric. These - are useful for measuring performance of a given block of code. - - **Counters** increment a counter each time a decorated method or context - manager is executed. These are useful for counting the number of times a - method is called, or the number of times an event occurs. - - **Gauges** return the value of a decorated method as a metric. This is - useful when you want to monitor the value returned by a method over time. - -Additionally, metrics can be sent directly, rather than using a context -manager or decorator, when appropriate. When used in this way, ironic-lib will -simply emit the value provided as the requested metric type. For example: - -.. code-block:: python - - from ironic_lib import metrics_utils - - METRICS = metrics_utils.get_metrics_logger(__name__) - - def my_node_failure_method(node): - if node.failed: - METRICS.send_counter(node.uuid, 1) - -The provided statsd backend natively supports all three metric types. For more -information about how statsd changes behavior based on the metric type, see -`statsd metric types `_ - - -Generated Developer Documentation -================================= +`ironic documentation `_. .. toctree:: :maxdepth: 1 - api/autoindex - - -References -========== - -Indices and tables -================== + Installation and Usage documentation + reference/index * :ref:`genindex` -* :ref:`modindex` * :ref:`search` diff --git a/doc/source/reference/index.rst b/doc/source/reference/index.rst new file mode 100644 index 00000000..0953572f --- /dev/null +++ b/doc/source/reference/index.rst @@ -0,0 +1,8 @@ +=========================== +Autogenerated API Reference +=========================== + +.. toctree:: + :maxdepth: 1 + + api/autoindex diff --git a/setup.cfg b/setup.cfg index 4e6332a4..32512300 100644 --- a/setup.cfg +++ b/setup.cfg @@ -35,6 +35,7 @@ autodoc_index_modules = True autodoc_exclude_modules = ironic_lib.common.i18n ironic_lib.tests.* +api_doc_dir = reference/api [build_sphinx] all_files = 1