2013-05-29 11:02:04 -07:00
|
|
|
.. _dev-quickstart:
|
2013-05-25 18:26:02 -07:00
|
|
|
|
2013-05-29 11:02:04 -07:00
|
|
|
=====================
|
|
|
|
Developer Quick-Start
|
|
|
|
=====================
|
2013-05-25 18:26:02 -07:00
|
|
|
|
|
|
|
This is a quick walkthrough to get you started developing code for Ironic.
|
2014-02-06 12:00:14 -08:00
|
|
|
This assumes you are already familiar with submitting code reviews to
|
2023-08-17 14:41:47 -07:00
|
|
|
an OpenStack project. If you are not, please begin by following the steps
|
|
|
|
in the
|
|
|
|
`OpenDev infra manual <https://docs.opendev.org/opendev/infra-manual/latest/gettingstarted.html>`_
|
|
|
|
to get yourself familiar with the general git workflow we use.
|
2013-05-25 18:26:02 -07:00
|
|
|
|
2023-08-17 14:41:47 -07:00
|
|
|
This guide is primarily technical in nature; for information on how the Ironic
|
|
|
|
team organizes work, please see `Ironic's contribution guide <https://docs.openstack.org/ironic/latest/contributor/contributing.html>`_.
|
2015-05-27 09:40:37 -04:00
|
|
|
|
2024-05-01 14:00:30 -07:00
|
|
|
This document covers :ref:`githooks`, :ref:`unit`, and :ref:`integrated`. New
|
|
|
|
contributors are recommended to setup git hooks, then continue with unit tests.
|
|
|
|
|
|
|
|
.. _githooks:
|
|
|
|
|
|
|
|
Git hooks
|
|
|
|
---------
|
|
|
|
Ironic uses multiple software packages to ensure code is styled as expected. A
|
|
|
|
convenient way to ensure your code complies with these rules is via the use of
|
|
|
|
`pre-commit <https://pre-commit.com/>`_.
|
|
|
|
|
|
|
|
To configure your environment for automatic checking of code spelling and linting
|
|
|
|
before commit, install ``pre-commit``:
|
|
|
|
|
|
|
|
pip install --user pre-commit
|
|
|
|
cd /path/to/ironic/checkout
|
|
|
|
pre-commit install --allow-missing-config
|
|
|
|
|
|
|
|
Now, before any commit, any changed lines will be run through our ``pre-commit``
|
|
|
|
checks. Contributors are still encouraged to run ``pep8`` and ``codespell``
|
|
|
|
tox environments before pushing code as an extra check.
|
|
|
|
|
|
|
|
More information about running tests in tox available in :ref:`unit`.
|
2016-07-25 15:31:50 +00:00
|
|
|
|
2023-08-17 14:41:47 -07:00
|
|
|
.. _integrated:
|
2013-05-25 18:26:02 -07:00
|
|
|
|
2023-08-17 14:41:47 -07:00
|
|
|
Integrated Testing Environments
|
|
|
|
-------------------------------
|
|
|
|
The ultimate in development environments for Ironic is a working system, with
|
|
|
|
mock bare metal hardware and a fully functional API service. There are three
|
|
|
|
ways to get environment, listed below.
|
2013-05-25 18:26:02 -07:00
|
|
|
|
2023-08-17 14:41:47 -07:00
|
|
|
.. note::
|
|
|
|
These environments may use automation that assume you are running on a VM.
|
|
|
|
Please do not use these environments on a system that you are not willing to
|
|
|
|
have wiped and reinstalled when complete.
|
|
|
|
|
|
|
|
.. list-table:: Testing Environments
|
|
|
|
:widths: 15, 70, 15
|
|
|
|
|
|
|
|
* - Environment
|
|
|
|
- Description/Uses
|
|
|
|
- How-To
|
|
|
|
* - Devstack
|
|
|
|
- Useful for testing Ironic with other OpenStack services. Also the
|
|
|
|
environment required for running or building Ironic's tempest tests.
|
|
|
|
Recommended for new contributors.
|
|
|
|
- :doc:`devstack-guide`
|
|
|
|
* - Bifrost
|
|
|
|
- Used for testing Ironic standalone with minimal setup or using real
|
|
|
|
hardware, or testing bifrost changes directly.
|
|
|
|
- :doc:`bifrost-dev-guide`
|
|
|
|
* - Local
|
|
|
|
- Ironic services running locally, without any other OpenStack services.
|
|
|
|
This can be useful for rapid prototyping, debugging, or testing database
|
|
|
|
migrations.
|
|
|
|
- :doc:`local-dev-guide`
|
|
|
|
|
|
|
|
.. _unit:
|
|
|
|
|
|
|
|
Unit Testing Environment
|
|
|
|
------------------------
|
|
|
|
For most people, unit testing is the quickest and easiest way to check
|
|
|
|
the validity of a change. Unlike a fully integrated testing environment,
|
|
|
|
unit tests can generally be safely run on a developer's workstation.
|
|
|
|
|
|
|
|
Ironic uses `tox <https://tox.readthedocs.io/en/latest/>`_ to orchestrate unit
|
|
|
|
tests and documentation building. Contributors are strongly encouraged to
|
|
|
|
validate code passes unit tests under a supported version of python before
|
|
|
|
pushing up a change. See the
|
|
|
|
`Project Testing Interface <https://governance.openstack.org/tc/reference/pti/python.html>`_
|
|
|
|
for the exact versions of python supported currently.
|
Documentation update
This patch contains several changes to the documentation which
were brought about by, initially, removing the webapi/v1 page and
replacing it with a link to the /api-ref/ page.
As I did that, I saw that our front page (index.html) needed to
be updated as well, and decided that the front page needed to
actually be completely rerwitten -- while preserving all the links.
Some of the TOC links from the front page were malformed because
subpages included more than one H1 heading, so I had to make small
changes in the api-audit-support and code-contribution-guide and
dev-quickstart pages, in order for the front page to render properly.
As I corrected the headings on dev-quickstart, I realized the page
was not comprehensively organized, and so decided to reorganize the
sections and make it easier to navigate.
Here is a bullet-point summary of this change:
* Major changes to content and organization of index page
* Moved the version history from webapi/v1 to dev/webapi-version-history
* Added API conceptual guide at dev/webapi
* Replaced webapi/v1 with a link to dev/webapi, in case anyone
bookmarked it
* Removed doc references to webapi/v1
* Merged the pages dev/contributing and dev/code-contribution-guide
* Removed duplicate H1 headers in deploy/api-audit-support
* Reorganized and renamed section headers in dev/dev-quickstart,
and made some substantive corrections and changes as well
* Updated wording at the top of the index and deploy/user-guide pages.
Change-Id: Ib418e1d4fdfab4f0e15560270f39922e33df3f12
2016-08-17 15:20:50 -07:00
|
|
|
|
|
|
|
System Prerequisites
|
2023-08-17 14:41:47 -07:00
|
|
|
====================
|
Documentation update
This patch contains several changes to the documentation which
were brought about by, initially, removing the webapi/v1 page and
replacing it with a link to the /api-ref/ page.
As I did that, I saw that our front page (index.html) needed to
be updated as well, and decided that the front page needed to
actually be completely rerwitten -- while preserving all the links.
Some of the TOC links from the front page were malformed because
subpages included more than one H1 heading, so I had to make small
changes in the api-audit-support and code-contribution-guide and
dev-quickstart pages, in order for the front page to render properly.
As I corrected the headings on dev-quickstart, I realized the page
was not comprehensively organized, and so decided to reorganize the
sections and make it easier to navigate.
Here is a bullet-point summary of this change:
* Major changes to content and organization of index page
* Moved the version history from webapi/v1 to dev/webapi-version-history
* Added API conceptual guide at dev/webapi
* Replaced webapi/v1 with a link to dev/webapi, in case anyone
bookmarked it
* Removed doc references to webapi/v1
* Merged the pages dev/contributing and dev/code-contribution-guide
* Removed duplicate H1 headers in deploy/api-audit-support
* Reorganized and renamed section headers in dev/dev-quickstart,
and made some substantive corrections and changes as well
* Updated wording at the top of the index and deploy/user-guide pages.
Change-Id: Ib418e1d4fdfab4f0e15560270f39922e33df3f12
2016-08-17 15:20:50 -07:00
|
|
|
|
|
|
|
The following packages cover the prerequisites for a local development
|
2023-08-17 14:41:47 -07:00
|
|
|
environment on most current distributions.
|
2013-05-25 18:26:02 -07:00
|
|
|
|
2015-05-04 20:32:56 +00:00
|
|
|
- Ubuntu/Debian::
|
2013-05-25 18:26:02 -07:00
|
|
|
|
2024-11-06 11:51:09 -06:00
|
|
|
sudo apt-get install build-essential python3-dev libssl-dev python3-pip libmysqlclient-dev libxml2-dev libxslt-dev libpq-dev git git-review libffi-dev gettext ipmitool psmisc graphviz libjpeg-dev qemu-utils
|
2015-05-04 20:32:56 +00:00
|
|
|
|
2021-03-08 11:48:42 +01:00
|
|
|
- RHEL/CentOS/Fedora::
|
2015-08-04 10:14:23 +01:00
|
|
|
|
2024-11-06 11:51:09 -06:00
|
|
|
sudo dnf install python3-devel openssl-devel python3-pip mysql-devel libxml2-devel libxslt-devel postgresql-devel git git-review libffi-devel gettext ipmitool psmisc graphviz gcc libjpeg-turbo-devel qemu-img
|
2015-08-04 10:14:23 +01:00
|
|
|
|
2021-03-08 11:48:42 +01:00
|
|
|
- openSUSE/SLE::
|
2014-11-14 08:00:23 -08:00
|
|
|
|
2024-11-06 11:51:09 -06:00
|
|
|
sudo zypper install git git-review libffi-devel libmysqlclient-devel libopenssl-devel libxml2-devel libxslt-devel postgresql-devel python3-devel python-nose python3-pip gettext-runtime psmisc qemu-img
|
2013-05-25 18:26:02 -07:00
|
|
|
|
2018-07-31 10:33:54 +01:00
|
|
|
To run the tests locally, it is a requirement that your terminal emulator
|
|
|
|
supports unicode with the ``en_US.UTF8`` locale. If you use locale-gen to
|
|
|
|
manage your locales, make sure you have enabled ``en_US.UTF8`` in
|
|
|
|
``/etc/locale.gen`` and rerun ``locale-gen``.
|
2015-05-27 09:40:37 -04:00
|
|
|
|
Documentation update
This patch contains several changes to the documentation which
were brought about by, initially, removing the webapi/v1 page and
replacing it with a link to the /api-ref/ page.
As I did that, I saw that our front page (index.html) needed to
be updated as well, and decided that the front page needed to
actually be completely rerwitten -- while preserving all the links.
Some of the TOC links from the front page were malformed because
subpages included more than one H1 heading, so I had to make small
changes in the api-audit-support and code-contribution-guide and
dev-quickstart pages, in order for the front page to render properly.
As I corrected the headings on dev-quickstart, I realized the page
was not comprehensively organized, and so decided to reorganize the
sections and make it easier to navigate.
Here is a bullet-point summary of this change:
* Major changes to content and organization of index page
* Moved the version history from webapi/v1 to dev/webapi-version-history
* Added API conceptual guide at dev/webapi
* Replaced webapi/v1 with a link to dev/webapi, in case anyone
bookmarked it
* Removed doc references to webapi/v1
* Merged the pages dev/contributing and dev/code-contribution-guide
* Removed duplicate H1 headers in deploy/api-audit-support
* Reorganized and renamed section headers in dev/dev-quickstart,
and made some substantive corrections and changes as well
* Updated wording at the top of the index and deploy/user-guide pages.
Change-Id: Ib418e1d4fdfab4f0e15560270f39922e33df3f12
2016-08-17 15:20:50 -07:00
|
|
|
Python Prerequisites
|
2023-08-17 14:41:47 -07:00
|
|
|
====================
|
2016-07-25 15:31:50 +00:00
|
|
|
|
2021-03-08 11:48:42 +01:00
|
|
|
We suggest to use at least tox 3.9, if your distribution has an older version,
|
|
|
|
you can install it using pip system-wise or better per user using the --user
|
|
|
|
option that by default will install the binary under $HOME/.local/bin, so you
|
|
|
|
need to be sure to have that path in $PATH; for example::
|
|
|
|
|
|
|
|
pip install tox --user
|
2015-05-04 20:32:56 +00:00
|
|
|
|
2021-03-08 11:48:42 +01:00
|
|
|
will install tox as ~/.local/bin/tox
|
2013-05-25 18:26:02 -07:00
|
|
|
|
2014-02-19 19:05:05 -08:00
|
|
|
You may need to explicitly upgrade virtualenv if you've installed the one
|
|
|
|
from your OS distribution and it is too old (tox will complain). You can
|
|
|
|
upgrade it individually, if you need to::
|
2013-05-25 18:26:02 -07:00
|
|
|
|
2023-08-17 14:41:47 -07:00
|
|
|
pip install --upgrade virtualenv --user
|
Documentation update
This patch contains several changes to the documentation which
were brought about by, initially, removing the webapi/v1 page and
replacing it with a link to the /api-ref/ page.
As I did that, I saw that our front page (index.html) needed to
be updated as well, and decided that the front page needed to
actually be completely rerwitten -- while preserving all the links.
Some of the TOC links from the front page were malformed because
subpages included more than one H1 heading, so I had to make small
changes in the api-audit-support and code-contribution-guide and
dev-quickstart pages, in order for the front page to render properly.
As I corrected the headings on dev-quickstart, I realized the page
was not comprehensively organized, and so decided to reorganize the
sections and make it easier to navigate.
Here is a bullet-point summary of this change:
* Major changes to content and organization of index page
* Moved the version history from webapi/v1 to dev/webapi-version-history
* Added API conceptual guide at dev/webapi
* Replaced webapi/v1 with a link to dev/webapi, in case anyone
bookmarked it
* Removed doc references to webapi/v1
* Merged the pages dev/contributing and dev/code-contribution-guide
* Removed duplicate H1 headers in deploy/api-audit-support
* Reorganized and renamed section headers in dev/dev-quickstart,
and made some substantive corrections and changes as well
* Updated wording at the top of the index and deploy/user-guide pages.
Change-Id: Ib418e1d4fdfab4f0e15560270f39922e33df3f12
2016-08-17 15:20:50 -07:00
|
|
|
|
|
|
|
Running Unit Tests Locally
|
|
|
|
==========================
|
|
|
|
If you haven't already, Ironic source code should be pulled directly from git::
|
2014-02-19 19:05:05 -08:00
|
|
|
|
2023-08-17 14:41:47 -07:00
|
|
|
# from a user-writable directory, usually $HOME or $HOME/dev
|
2019-04-22 11:48:26 +08:00
|
|
|
git clone https://opendev.org/openstack/ironic
|
2014-02-19 19:05:05 -08:00
|
|
|
cd ironic
|
|
|
|
|
2013-05-25 18:26:02 -07:00
|
|
|
|
2024-05-01 14:00:30 -07:00
|
|
|
Most of the time, you will want to run codespell, unit tests, and pep8 checks.
|
|
|
|
This can be done with the following command::
|
2023-08-17 14:41:47 -07:00
|
|
|
|
2024-05-01 14:00:30 -07:00
|
|
|
tox -e codespell,pep8,py3
|
2023-08-17 14:41:47 -07:00
|
|
|
|
|
|
|
Ironic has multiple test environments that can be run by tox. An incomplete
|
|
|
|
list of environments and what they do is below. Please reference the ``tox.ini``
|
|
|
|
file in the project you're working on for a complete, up-to-date list.
|
|
|
|
|
|
|
|
.. list-table:: Tox Environments
|
|
|
|
:widths: 20, 80
|
|
|
|
|
|
|
|
* - Environment
|
|
|
|
- Description
|
|
|
|
* - pep8
|
|
|
|
- Run style checks on code, documentation, and release notes.
|
2024-05-01 14:00:30 -07:00
|
|
|
* - codespell
|
|
|
|
- Check code against a list of known-misspelled words.
|
2023-08-17 14:41:47 -07:00
|
|
|
* - py<version>
|
|
|
|
- Run unit tests with the specified python version. For example, ``py310`` will run the unit tests with python 3.10.
|
|
|
|
* - unit-with-driver-libs
|
|
|
|
- Run unit tests with the default python3 on the system, but also includes driver-specific libraries and the tests they enable.
|
|
|
|
* - mysql-migrations
|
|
|
|
- Run MySQL database migration unit tests. Setup database first using ``tools/test-setup.sh`` in Ironic repo.
|
|
|
|
* - docs
|
|
|
|
- Build and validate documentation.
|
|
|
|
* - releasenotes
|
|
|
|
- Build and validate release notes using ``reno``.
|
|
|
|
* - api-ref
|
|
|
|
- Build and validate API reference documentation.
|
|
|
|
* - genconfig
|
|
|
|
- Generates example configuration file.
|
|
|
|
* - genpolicy
|
|
|
|
- Generates example policy configuration file.
|
|
|
|
* - venv
|
|
|
|
- Creates a venv, with dependencies installed, for running commands in e.g. ``tox -evenv -- reno new my-release-note``
|
|
|
|
|
|
|
|
|
|
|
|
You may also pass options to the test programs using positional arguments.
|
2018-06-18 12:06:16 +09:00
|
|
|
To run a specific unit test, this passes the desired test
|
|
|
|
(regex string) to `stestr <https://pypi.org/project/stestr>`_::
|
2013-05-25 18:26:02 -07:00
|
|
|
|
2023-08-17 14:41:47 -07:00
|
|
|
# run a specific test for Python 3.10
|
|
|
|
tox -epy310 -- test_conductor
|
2013-05-25 18:26:02 -07:00
|
|
|
|
2016-06-03 10:21:33 +01:00
|
|
|
Debugging unit tests
|
2023-08-17 14:41:47 -07:00
|
|
|
====================
|
2016-06-03 10:21:33 +01:00
|
|
|
|
|
|
|
In order to break into the debugger from a unit test we need to insert
|
|
|
|
a breaking point to the code:
|
|
|
|
|
|
|
|
.. code-block:: python
|
|
|
|
|
|
|
|
import pdb; pdb.set_trace()
|
|
|
|
|
|
|
|
Then run ``tox`` with the debug environment as one of the following::
|
|
|
|
|
|
|
|
tox -e debug
|
|
|
|
tox -e debug test_file_name
|
|
|
|
tox -e debug test_file_name.TestClass
|
|
|
|
tox -e debug test_file_name.TestClass.test_name
|
|
|
|
|
2019-10-03 16:04:57 +02:00
|
|
|
For more information see the
|
|
|
|
:oslotest-doc:`oslotest documentation <user/features.html#debugging-with-oslo-debug-helper>`.
|
2016-06-03 10:21:33 +01:00
|
|
|
|
2014-02-06 12:00:14 -08:00
|
|
|
|
2023-08-17 14:41:47 -07:00
|
|
|
Other tests
|
|
|
|
===========
|
|
|
|
Ironic also has a number of tests built with Tempest. For more information
|
|
|
|
about writing or running those tests, see :ref:`tempest`.
|
2016-04-19 11:26:01 +01:00
|
|
|
|
Enable OSProfiler support in Ironic
This patch does the following:
* Adds osprofiler wsgi middleware
This middleware is used for 2 things:
- It checks that person who wants to trace is trusted and knows
secret HMAC key.
- It starts tracing in case of proper trace headers
and adds first wsgi trace point, with info about HTTP request.
* Adds initialization of osprofiler at start of service
- Initialize and set an oslo.messaging based notifier instance
to osprofiler, which will be used to send notifications to Ceilometer.
* Traces HTTP/RPC/DB API calls and SQL requests
NOTE to test this patch:
1) Make the following changes in localrc to configure DevStack to enable
OSProfiler:
enable_plugin panko https://git.openstack.org/openstack/panko
enable_plugin ceilometer https://git.openstack.org/openstack/ceilometer
enable_plugin osprofiler https://git.openstack.org/openstack/osprofiler
# Enable the following services
CEILOMETER_NOTIFICATION_TOPICS=notifications,profiler
ENABLED_SERVICES+=,ceilometer-acompute,ceilometer-acentral
ENABLED_SERVICES+=,ceilometer-anotification,ceilometer-collector
ENABLED_SERVICES+=,ceilometer-alarm-evaluator,ceilometer-alarm-notifier
ENABLED_SERVICES+=,ceilometer-api
NOTE: the order of enabling plugins matters.
2) Run stack.sh. Once DevStack environment is setup, enable profiler options
in ironic.conf and restart ironic services:
[profiler]
enabled = true
hmac_keys = SECRET_KEY
trace_sqlalchemy = true
3) Use openstackclient and run baremetal command with
--os-profile SECRET_KEY
[--profile can be used, but it is deprecated.]
For example, the following will cause the <trace-id> to be printed
after node list:
$ openstack --os-profile SECRET_KEY baremetal node list
.....
.....
Trace ID: <trace-id>
Display trace with command:
osprofiler trace show --html <trace-id>
4) The trace results can be saved using this command:
$ osprofiler trace show --html <trace-id> --out trace.html
OSprofiler spec: https://review.openstack.org/#/c/103825/
Co-Authored-By: Tovin Seven <vinhnt@vn.fujitsu.com>
Co-Authored-By: Hieu LE <hieulq@vn.fujitsu.com>
Partial-Bug: #1560704
Change-Id: Icd3d7c62cf7442de8a77fc67f119ae9b03725f02
2016-08-18 16:55:56 -07:00
|
|
|
|
|
|
|
OSProfiler Tracing in Ironic
|
2023-08-17 14:41:47 -07:00
|
|
|
----------------------------
|
Enable OSProfiler support in Ironic
This patch does the following:
* Adds osprofiler wsgi middleware
This middleware is used for 2 things:
- It checks that person who wants to trace is trusted and knows
secret HMAC key.
- It starts tracing in case of proper trace headers
and adds first wsgi trace point, with info about HTTP request.
* Adds initialization of osprofiler at start of service
- Initialize and set an oslo.messaging based notifier instance
to osprofiler, which will be used to send notifications to Ceilometer.
* Traces HTTP/RPC/DB API calls and SQL requests
NOTE to test this patch:
1) Make the following changes in localrc to configure DevStack to enable
OSProfiler:
enable_plugin panko https://git.openstack.org/openstack/panko
enable_plugin ceilometer https://git.openstack.org/openstack/ceilometer
enable_plugin osprofiler https://git.openstack.org/openstack/osprofiler
# Enable the following services
CEILOMETER_NOTIFICATION_TOPICS=notifications,profiler
ENABLED_SERVICES+=,ceilometer-acompute,ceilometer-acentral
ENABLED_SERVICES+=,ceilometer-anotification,ceilometer-collector
ENABLED_SERVICES+=,ceilometer-alarm-evaluator,ceilometer-alarm-notifier
ENABLED_SERVICES+=,ceilometer-api
NOTE: the order of enabling plugins matters.
2) Run stack.sh. Once DevStack environment is setup, enable profiler options
in ironic.conf and restart ironic services:
[profiler]
enabled = true
hmac_keys = SECRET_KEY
trace_sqlalchemy = true
3) Use openstackclient and run baremetal command with
--os-profile SECRET_KEY
[--profile can be used, but it is deprecated.]
For example, the following will cause the <trace-id> to be printed
after node list:
$ openstack --os-profile SECRET_KEY baremetal node list
.....
.....
Trace ID: <trace-id>
Display trace with command:
osprofiler trace show --html <trace-id>
4) The trace results can be saved using this command:
$ osprofiler trace show --html <trace-id> --out trace.html
OSprofiler spec: https://review.openstack.org/#/c/103825/
Co-Authored-By: Tovin Seven <vinhnt@vn.fujitsu.com>
Co-Authored-By: Hieu LE <hieulq@vn.fujitsu.com>
Partial-Bug: #1560704
Change-Id: Icd3d7c62cf7442de8a77fc67f119ae9b03725f02
2016-08-18 16:55:56 -07:00
|
|
|
|
|
|
|
OSProfiler is an OpenStack cross-project profiling library. It is being
|
|
|
|
used among OpenStack projects to look at performance issues and detect
|
|
|
|
bottlenecks. For details on how OSProfiler works and how to use it in ironic,
|
|
|
|
please refer to `OSProfiler Support Documentation <osprofiler-support>`_.
|
|
|
|
|
|
|
|
|
2014-02-19 19:05:05 -08:00
|
|
|
Building developer documentation
|
2023-08-17 14:41:47 -07:00
|
|
|
--------------------------------
|
2014-02-06 12:00:14 -08:00
|
|
|
|
2014-02-19 19:05:05 -08:00
|
|
|
If you would like to build the documentation locally, eg. to test your
|
|
|
|
documentation changes before uploading them for review, run these
|
2016-08-03 17:32:22 +00:00
|
|
|
commands to build the documentation set:
|
|
|
|
|
2023-08-17 14:41:47 -07:00
|
|
|
- On the machine with the ironic checkout::
|
2014-02-19 19:05:05 -08:00
|
|
|
|
2023-08-17 14:41:47 -07:00
|
|
|
# change into the ironic source code directory
|
|
|
|
cd ~/ironic
|
2014-02-19 19:05:05 -08:00
|
|
|
|
|
|
|
# build the docs
|
2015-05-20 16:36:35 +02:00
|
|
|
tox -edocs
|
2014-02-06 12:00:14 -08:00
|
|
|
|
2023-08-17 14:41:47 -07:00
|
|
|
To view the built documentation locally, open up the top level index.html in
|
|
|
|
your browser. For an example user named ``bob`` with the Ironic checkout in
|
|
|
|
their homedir, the URL to put in the browser would be::
|
2014-02-19 19:05:05 -08:00
|
|
|
|
2023-08-17 14:41:47 -07:00
|
|
|
file:///home/bob/ironic/doc/build/html/index.html
|
2016-06-03 20:25:54 +03:00
|
|
|
|
2023-08-17 14:41:47 -07:00
|
|
|
If you're building docs on a remote VM, you can use python's SimpleHTTPServer
|
|
|
|
to setup a quick webserver to check your docs build::
|
2016-08-03 17:32:22 +00:00
|
|
|
|
|
|
|
# Change directory to the newly built HTML files
|
|
|
|
cd ~/ironic/doc/build/html/
|
|
|
|
|
|
|
|
# Create a server using python on port 8000
|
|
|
|
python -m SimpleHTTPServer 8000
|
|
|
|
|
2023-08-17 14:41:47 -07:00
|
|
|
# Now use your browser to open the top-level index.html located at:
|
|
|
|
http://remote_ip:8000
|