From 20ccb58e675ee5598183fd1366ecf4e8502faa2d Mon Sep 17 00:00:00 2001 From: Akihiro Motoki Date: Thu, 22 Feb 2018 08:12:49 +0900 Subject: [PATCH] Improve doc structure The current top page of heat-dashboard doc is a bit tricky. The content of installation is duplicated, for example. This commit revisit the document structure. * Drop installation instruction from README * Drop meaningless indices and tables (which are not working) * Move DevStack setup to the contributor document * Merge installation_contents.rst into installation.rst Change-Id: I897cfe0094358db63a364088fd2b977e234101e8 --- README.rst | 84 ++------------------ doc/source/contributor/devstack.rst | 13 +++ doc/source/contributor/index.rst | 2 +- doc/source/index.rst | 23 ++---- doc/source/install/installation.rst | 51 +++++++++++- doc/source/install/installation_contents.rst | 63 --------------- doc/source/readme.rst | 1 - 7 files changed, 80 insertions(+), 157 deletions(-) create mode 100644 doc/source/contributor/devstack.rst delete mode 100644 doc/source/install/installation_contents.rst delete mode 100644 doc/source/readme.rst diff --git a/README.rst b/README.rst index 4fc1814..9fff86d 100644 --- a/README.rst +++ b/README.rst @@ -1,83 +1,15 @@ -======================== -Team and repository tags -======================== +========================== +Welcome to Heat Dashboard! +========================== -.. image:: https://governance.openstack.org/tc/badges/heat-dashboard.svg - :target: http://governance.openstack.org/reference/tags/index.html - -.. Change things from this point on - -============== -Heat Dashboard -============== - -Horizon plugin for Heat +Heat dashboard is a horizon plugin for Heat. * License: Apache license * Source: http://git.openstack.org/cgit/openstack/heat-dashboard * Bugs: http://bugs.launchpad.net/heat-dashboard +Team and repository tags +------------------------ -Use Heat Dashboard in DevStack ------------------------------- - -Set up your ``local.conf`` to enable heat-dashboard:: - - [[local|localrc]] - enable_plugin heat-dashboard https://git.openstack.org/openstack/heat-dashboard - - -.. note:: - - You also need to install Heat itself into DevStack to use Heat Dashboard. - -Manual Installation -------------------- - -Clone both Horizon and Heat Dashboard repositories:: - - git clone https://github.com/openstack/horizon - git clone https://github.com/openstack/heat-dashboard - -Create a virtual environment and install Horizon relevant packages:: - - pip install -r horizon/requirements.txt - -Create your ``local_settings.py`` file:: - - cp horizon/openstack_dashboard/local/local_settings.py.example \ - horizon/openstack_dashboard/local/local_settings.py - -Open newly created ``local_settings.py`` with your text editor, -and set some parameter to connect to your OpenStack environment: - -- Set ``OPENSTACK_HOST`` as hostname or IP address of your OpenStack server. - -- Verify that the ``OPENSTACK_KEYSTONE_URL`` and - ``OPENSTACK_KEYSTONE_DEFAULT_ROLE`` settings are correct for your - environment. (They should be correct unless you modified your - OpenStack server to change them.) - -Install Heat Dashboard with all relevant packages to your Horizon environment:: - - pip install -e ./heat-dashboard/ - -Enable heat-dashboard plugin in your Horizon environment:: - - cp heat-dashboard/heat_dashboard/enabled/* \ - horizon/openstack_dashboard/local/enabled - - cp heat-dashboard/heat_dashboard/conf/* \ - horizon/openstack_dashboard/conf/ - - cp heat-dashboard/heat_dashboard/local_settings.d/* \ - horizon/openstack_dashboard/local/local_settings.d/ - - -Finally you can launch Horizon with Heat Dashboard plugin:: - - cd horizon - python manage.py runserver 0.0.0.0:8080 - -Now you can connect to your Horizon including Heat Dashboard plugin -from your browser with URL http://localhost:8080/. +.. image:: https://governance.openstack.org/tc/badges/heat-dashboard.svg + :target: http://governance.openstack.org/reference/tags/index.html diff --git a/doc/source/contributor/devstack.rst b/doc/source/contributor/devstack.rst new file mode 100644 index 0000000..747f688 --- /dev/null +++ b/doc/source/contributor/devstack.rst @@ -0,0 +1,13 @@ +============================== +Use Heat Dashboard in DevStack +============================== + +Set up your ``local.conf`` to enable heat-dashboard:: + + [[local|localrc]] + enable_plugin heat-dashboard https://git.openstack.org/openstack/heat-dashboard + + +.. note:: + + You also need to install Heat itself into DevStack to use Heat Dashboard. diff --git a/doc/source/contributor/index.rst b/doc/source/contributor/index.rst index 036e449..e6062ca 100644 --- a/doc/source/contributor/index.rst +++ b/doc/source/contributor/index.rst @@ -6,4 +6,4 @@ :maxdepth: 2 contributing - + devstack diff --git a/doc/source/index.rst b/doc/source/index.rst index e4368a0..88745e9 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -3,24 +3,17 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. -============================================== -Welcome to the documentation of Heat Dashboard -============================================== +.. the main title comes from README.rst -Contents: +.. include:: ../../README.rst + +Contents +-------- .. toctree:: :maxdepth: 2 - readme - install/index + Installation Guide + Configuration Guide + User Documentation contributor/index - configuration/index - user/index - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` diff --git a/doc/source/install/installation.rst b/doc/source/install/installation.rst index 3ff67f8..ad6eb14 100644 --- a/doc/source/install/installation.rst +++ b/doc/source/install/installation.rst @@ -2,4 +2,53 @@ Installation ============ -.. include:: installation_contents.rst +Manual Installation +------------------- + +Clone both Horizon and Heat Dashboard repositories:: + + git clone https://github.com/openstack/horizon + git clone https://github.com/openstack/heat-dashboard + +Create a virtual environment and install Horizon relevant packages:: + + pip install -r horizon/requirements.txt + +Create your ``local_settings.py`` file:: + + cp horizon/openstack_dashboard/local/local_settings.py.example \ + horizon/openstack_dashboard/local/local_settings.py + +Open newly created ``local_settings.py`` with your text editor, +and set some parameter to connect to your OpenStack environment: + +- Set ``OPENSTACK_HOST`` as hostname or IP address of your OpenStack server. + +- Verify that the ``OPENSTACK_KEYSTONE_URL`` and + ``OPENSTACK_KEYSTONE_DEFAULT_ROLE`` settings are correct for your + environment. (They should be correct unless you modified your + OpenStack server to change them.) + +Install Heat Dashboard with all relevant packages to your Horizon environment:: + + pip install -e ./heat-dashboard/ + +Enable heat-dashboard plugin in your Horizon environment:: + + cp heat-dashboard/heat_dashboard/enabled/* \ + horizon/openstack_dashboard/local/enabled + + cp heat-dashboard/heat_dashboard/conf/* \ + horizon/openstack_dashboard/conf/ + + cp heat-dashboard/heat_dashboard/local_settings.d/* \ + horizon/openstack_dashboard/local/local_settings.d/ + + +Finally you can launch Horizon with Heat Dashboard plugin:: + + cd horizon + python manage.py runserver 0.0.0.0:8080 + +Now you can connect to your Horizon including Heat Dashboard plugin +from your browser with URL http://localhost:8080/. diff --git a/doc/source/install/installation_contents.rst b/doc/source/install/installation_contents.rst deleted file mode 100644 index b41bb3e..0000000 --- a/doc/source/install/installation_contents.rst +++ /dev/null @@ -1,63 +0,0 @@ -Use Heat Dashboard in DevStack ------------------------------- - -Set up your ``local.conf`` to enable heat-dashboard:: - - [[local|localrc]] - enable_plugin heat-dashboard https://git.openstack.org/openstack/heat-dashboard - - -.. note:: - - You also need to install Heat itself into DevStack to use Heat Dashboard. - -Manual Installation -------------------- - -Clone both Horizon and Heat Dashboard repositories:: - - git clone https://github.com/openstack/horizon - git clone https://github.com/openstack/heat-dashboard - -Create a virtual environment and install Horizon relevant packages:: - - pip install -r horizon/requirements.txt - -Create your ``local_settings.py`` file:: - - cp horizon/openstack_dashboard/local/local_settings.py.example \ - horizon/openstack_dashboard/local/local_settings.py - -Open newly created ``local_settings.py`` with your text editor, -and set some parameter to connect to your OpenStack environment: - -- Set ``OPENSTACK_HOST`` as hostname or IP address of your OpenStack server. - -- Verify that the ``OPENSTACK_KEYSTONE_URL`` and - ``OPENSTACK_KEYSTONE_DEFAULT_ROLE`` settings are correct for your - environment. (They should be correct unless you modified your - OpenStack server to change them.) - -Install Heat Dashboard with all relevant packages to your Horizon environment:: - - pip install -e ./heat-dashboard/ - -Enable heat-dashboard plugin in your Horizon environment:: - - cp heat-dashboard/heat_dashboard/enabled/* \ - horizon/openstack_dashboard/local/enabled - - cp heat-dashboard/heat_dashboard/conf/* \ - horizon/openstack_dashboard/conf/ - - cp heat-dashboard/heat_dashboard/local_settings.d/* \ - horizon/openstack_dashboard/local/local_settings.d/ - - -Finally you can launch Horizon with Heat Dashboard plugin:: - - cd horizon - python manage.py runserver 0.0.0.0:8080 - -Now you can connect to your Horizon including Heat Dashboard plugin -from your browser with URL http://localhost:8080/. diff --git a/doc/source/readme.rst b/doc/source/readme.rst deleted file mode 100644 index a6210d3..0000000 --- a/doc/source/readme.rst +++ /dev/null @@ -1 +0,0 @@ -.. include:: ../../README.rst