From df7319b80d0a7d0d9359aeffb3f07ee9c0fefc8e Mon Sep 17 00:00:00 2001 From: Akihiro Motoki Date: Sat, 6 Jan 2018 20:31:46 +0900 Subject: [PATCH] Reorganize manila-ui documentation This commit reorganizes the doc structure in the way suggested by doc-migration spec. Note that user/ is not touched by this commit as I plan to update it in a subsequent patch which moves manila-ui user/admin guide from horizon. Change-Id: I3c644c33cb912397bd1d5ee890f4991ac3e26501 --- CONTRIBUTING.rst | 6 +- README.rst | 181 ++-------------------------- doc/source/configuration/index.rst | 33 +++++ doc/source/contributor/features.rst | 36 ++++++ doc/source/contributor/index.rst | 10 ++ doc/source/contributor/readme.rst | 1 - doc/source/contributor/testing.rst | 43 +++++++ doc/source/index.rst | 14 ++- doc/source/install/installation.rst | 56 ++++++++- 9 files changed, 192 insertions(+), 188 deletions(-) create mode 100644 doc/source/configuration/index.rst create mode 100644 doc/source/contributor/features.rst create mode 100644 doc/source/contributor/index.rst delete mode 100644 doc/source/contributor/readme.rst create mode 100644 doc/source/contributor/testing.rst diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 86e33782..c075afe8 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -1,16 +1,16 @@ If you would like to contribute to the development of OpenStack, you must follow the steps in this page: - https://docs.openstack.org/infra/manual/developers.html +https://docs.openstack.org/infra/manual/developers.html Once those steps have been completed, changes to OpenStack should be submitted for review via the Gerrit tool, following the workflow documented at: - https://docs.openstack.org/infra/manual/developers.html#development-workflow +https://docs.openstack.org/infra/manual/developers.html#development-workflow Pull requests submitted through GitHub will be ignored. Bugs should be filed on Launchpad, not GitHub: - https://bugs.launchpad.net/manila-ui \ No newline at end of file +https://bugs.launchpad.net/manila-ui diff --git a/README.rst b/README.rst index b77250e1..b2e4f993 100644 --- a/README.rst +++ b/README.rst @@ -1,179 +1,14 @@ -======================== -Team and repository tags -======================== - -.. image:: https://governance.openstack.org/badges/manila-ui.svg - :target: https://governance.openstack.org/reference/tags/index.html - -.. Change things from this point on - -=============================== -manila-ui -=============================== - -Manila Management Dashboard +======================================= +manila-ui - Manila Management Dashboard +======================================= * Free software: Apache license - -.. Uncomment these bullet items when the project is integrated into OpenStack - +* Documentation: https://docs.openstack.org/manila-ui/latest/ * Source: https://git.openstack.org/cgit/openstack/manila-ui * Bugs: https://bugs.launchpad.net/manila-ui +Team and repository tags +------------------------ -Installation instructions -------------------------- - -For Manila UI installation in RDO, see: -`Installing Manila UI in RDO`_. For other distributions, begin by -cloning the Horizon and Manila UI repositories:: - - git clone https://github.com/openstack/horizon - git clone https://github.com/openstack/manila-ui - -Create a virtual environment and install Horizon dependencies:: - - cd horizon - python tools/install_venv.py - -Set up your ``local_settings.py`` file:: - - cp openstack_dashboard/local/local_settings.py.example openstack_dashboard/local/local_settings.py - -Open up the copied ``local_settings.py`` file in your preferred text -editor. You will want to customize several settings: - -- ``OPENSTACK_HOST`` should be configured with the hostname 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 Manila UI with all dependencies in your virtual environment:: - - tools/with_venv.sh pip install -e ../manila-ui/ - -And enable it in Horizon:: - - cp ../manila-ui/manila_ui/local/enabled/_*.py openstack_dashboard/local/enabled - cp ../manila-ui/manila_ui/local/local_settings.d/_90_manila_*.py openstack_dashboard/local/local_settings.d - - -Starting the app ----------------- - -If everything has gone according to plan, you should be able to run:: - - ./run_tests.sh --runserver 0.0.0.0:8080 - -and have the application start on port 8080. The horizon dashboard will -be located at http://localhost:8080/ - -Installing Manila UI in RDO ---------------------------- - -In order to install Manila UI in [RDO](https://www.rdoproject.org), -please follow the steps below (you may need to use `sudo` privileges -if you are not root):: - -# yum install -y openstack-manila-ui -# systemctl restart httpd -# systemctl restart memcached - -Manila UI will now be available through OpenStack Horizon; look for -the Shares tab under Project > Compute. You can access Horizon with -Manila UI using the same URL and port as before. - -_`Configuration` ----------------- - -It is possible to enable or disable some Manila UI features. To do so, -look for files located in "manila_ui/local/local_settings.d/" directory, -where you can redefine the values of the OPENSTACK_MANILA_FEATURES dict:: - - * enable_share_groups - * enable_replication - * enable_migration - * enable_public_share_type_creation - * enable_public_share_group_type_creation - * enable_public_shares - * enabled_share_protocols - -By default, enabled_share_protocols within the OPENSTACK_MANILA_FEATURES -dict contains a list with all the supported protocols. The operator can -change this to display to users only those protocols that has been deployed -and are available to use. E.g. if only NFS is available, the operator is -expected to redefine enabled_share_protocols as follows: - -.. code-block:: python - - OPENSTACK_MANILA_FEATURES = { - 'enable_share_groups': True, - 'enable_replication': True, - 'enable_migration': True, - 'enable_public_share_type_creation': True, - 'enable_public_share_group_type_creation': True, - 'enable_public_shares': True, - 'enabled_share_protocols': ['NFS'], - } - -New Features ------------- - -When implementing a new feature, you may think about making it optional, -so it could be enabled or disabled in different deployments. - -How to use it: - -.. code-block:: python - - from django.conf import settings - manila_config = getattr(settings, 'OPENSTACK_MANILA_FEATURES', {}) - manila_config.get('your_new_config_option', 'value_of_config_option') - -See `Configuration`_ section for more configuration details. - -It is also expected that each addition of new logic to Manila UI is covered by -unit tests. - -Test modules should be located under "manila_ui/tests", satisfying -the following template when tests are written for a specific module:: - - manila_ui[/tests]/path/to/[test_]modulename.py - -However, when testing the flow between different modules (using test app), -the tests can be added to a test module that can satisfy -the following template:: - - manila_ui[/tests]/path/to/directory/tests.py - -Manila UI tests use the mock library for testing. - -Running unit tests ------------------- - -The unit tests can be executed directly from within this Manila UI plugin -project directory by using:: - - $ cd ../manila-ui - $ tox - -This is made possible by the dependency in test-requirements.txt upon the -horizon source, which pulls down all of the horizon and openstack_dashboard -modules that the plugin uses. - -To run only py27 unit tests, use following command:: - - $ tox -e py27 - -To run only py34 unit tests, use following command:: - - $ tox -e py34 - -To run unit tests using specific Django version use the following:: - - $ tox -e py27dj17 - $ tox -e py27dj18 - $ tox -e py27dj19 - $ tox -e py27dj110 +.. image:: https://governance.openstack.org/badges/manila-ui.svg + :target: https://governance.openstack.org/reference/tags/index.html diff --git a/doc/source/configuration/index.rst b/doc/source/configuration/index.rst new file mode 100644 index 00000000..eaa7c07c --- /dev/null +++ b/doc/source/configuration/index.rst @@ -0,0 +1,33 @@ +============= +Configuration +============= + +It is possible to enable or disable some Manila UI features. To do so, +look for files located in "manila_ui/local/local_settings.d/" directory, +where you can redefine the values of the OPENSTACK_MANILA_FEATURES dict: + +* enable_share_groups +* enable_replication +* enable_migration +* enable_public_share_type_creation +* enable_public_share_group_type_creation +* enable_public_shares +* enabled_share_protocols + +By default, enabled_share_protocols within the OPENSTACK_MANILA_FEATURES +dict contains a list with all the supported protocols. The operator can +change this to display to users only those protocols that has been deployed +and are available to use. E.g. if only NFS is available, the operator is +expected to redefine enabled_share_protocols as follows: + +.. code-block:: python + + OPENSTACK_MANILA_FEATURES = { + 'enable_share_groups': True, + 'enable_replication': True, + 'enable_migration': True, + 'enable_public_share_type_creation': True, + 'enable_public_share_group_type_creation': True, + 'enable_public_shares': True, + 'enabled_share_protocols': ['NFS'], + } diff --git a/doc/source/contributor/features.rst b/doc/source/contributor/features.rst new file mode 100644 index 00000000..e1f774dd --- /dev/null +++ b/doc/source/contributor/features.rst @@ -0,0 +1,36 @@ +============ +New Features +============ + +When implementing a new feature, you may think about making it optional, +so it could be enabled or disabled in different deployments. + +How to use it: + +.. code-block:: python + + from django.conf import settings + manila_config = getattr(settings, 'OPENSTACK_MANILA_FEATURES', {}) + manila_config.get('your_new_config_option', 'value_of_config_option') + +See :doc:`/configuration/index` section for more configuration details. + +It is also expected that each addition of new logic to Manila UI is covered by +unit tests. + +Test modules should be located under "manila_ui/tests", satisfying +the following template when tests are written for a specific module: + +.. code-block:: none + + manila_ui[/tests]/path/to/[test_]modulename.py + +However, when testing the flow between different modules (using test app), +the tests can be added to a test module that can satisfy +the following template: + +.. code-block:: none + + manila_ui[/tests]/path/to/directory/tests.py + +Manila UI tests use the mock library for testing. diff --git a/doc/source/contributor/index.rst b/doc/source/contributor/index.rst new file mode 100644 index 00000000..8b6c3414 --- /dev/null +++ b/doc/source/contributor/index.rst @@ -0,0 +1,10 @@ +========================= +Contributor Documentation +========================= + +.. toctree:: + :maxdepth: 2 + + contributing + testing + features diff --git a/doc/source/contributor/readme.rst b/doc/source/contributor/readme.rst deleted file mode 100644 index e4a3ad51..00000000 --- a/doc/source/contributor/readme.rst +++ /dev/null @@ -1 +0,0 @@ -.. include:: ../../../README.rst diff --git a/doc/source/contributor/testing.rst b/doc/source/contributor/testing.rst new file mode 100644 index 00000000..3876d6c5 --- /dev/null +++ b/doc/source/contributor/testing.rst @@ -0,0 +1,43 @@ +======= +Testing +======= + +Starting the app +---------------- + +If everything has gone according to plan, you should be able to run: + +.. code-block:: console + + ./run_tests.sh --runserver 0.0.0.0:8080 + +and have the application start on port 8080. The horizon dashboard will +be located at http://localhost:8080/ + +Running unit tests +------------------ + +The unit tests can be executed directly from within this Manila UI plugin +project directory by using:: + + $ cd ../manila-ui + $ tox + +This is made possible by the dependency in test-requirements.txt upon the +horizon source, which pulls down all of the horizon and openstack_dashboard +modules that the plugin uses. + +To run only py27 unit tests, use following command:: + + $ tox -e py27 + +To run only py34 unit tests, use following command:: + + $ tox -e py34 + +To run unit tests using specific Django version use the following:: + + $ tox -e py27dj17 + $ tox -e py27dj18 + $ tox -e py27dj19 + $ tox -e py27dj110 diff --git a/doc/source/index.rst b/doc/source/index.rst index e00d6978..cf5cf41f 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -3,21 +3,23 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. -Welcome to manila-ui's documentation! -===================================== +.. the main title comes from README.rst -Contents: +.. include:: ../../README.rst + +Contents +-------- .. toctree:: :maxdepth: 2 - contributor/readme install/installation + configuration/index user/usage - contributor/contributing + contributor/index Indices and tables -================== +------------------ * :ref:`genindex` * :ref:`search` diff --git a/doc/source/install/installation.rst b/doc/source/install/installation.rst index 4d6d4c58..70277ca6 100644 --- a/doc/source/install/installation.rst +++ b/doc/source/install/installation.rst @@ -2,11 +2,57 @@ Installation ============ -At the command line:: +Manual Installation +------------------- - $ pip install manila-ui +For Manila UI installation in RDO, see: :ref:`install-rdo`. +For other distributions, begin by +cloning the Horizon and Manila UI repositories:: -Or, if you have virtualenvwrapper installed:: + git clone https://github.com/openstack/horizon + git clone https://github.com/openstack/manila-ui - $ mkvirtualenv manila-ui - $ pip install manila-ui \ No newline at end of file +Create a virtual environment and install Horizon dependencies:: + + cd horizon + python tools/install_venv.py + +Set up your ``local_settings.py`` file:: + + cp openstack_dashboard/local/local_settings.py.example openstack_dashboard/local/local_settings.py + +Open up the copied ``local_settings.py`` file in your preferred text +editor. You will want to customize several settings: + +- ``OPENSTACK_HOST`` should be configured with the hostname 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 Manila UI with all dependencies in your virtual environment:: + + tools/with_venv.sh pip install -e ../manila-ui/ + +And enable it in Horizon:: + + cp ../manila-ui/manila_ui/local/enabled/_*.py openstack_dashboard/local/enabled + cp ../manila-ui/manila_ui/local/local_settings.d/_90_manila_*.py openstack_dashboard/local/local_settings.d + +.. _install-rdo: + +Installing Manila UI in RDO +--------------------------- + +In order to install Manila UI in `RDO `__, +please follow the steps below (you may need to use `sudo` privileges +if you are not root):: + +# yum install -y openstack-manila-ui +# systemctl restart httpd +# systemctl restart memcached + +Manila UI will now be available through OpenStack Horizon; look for +the Shares tab under Project > Compute. You can access Horizon with +Manila UI using the same URL and port as before.