From 4b794472a84c7d2680bf3cb017dc548530f82d41 Mon Sep 17 00:00:00 2001 From: Luka Peschke Date: Thu, 29 Nov 2018 10:06:27 +0100 Subject: [PATCH] Change the documentation layout This changes the documentation layout according to the previously submitted spec. Change-Id: I9aa879af23ae4e993da60186eddaef8d22f59e79 Story: 2004179 Task: 28152 --- .../{arch.rst => admin/architecture.rst} | 0 .../configuration/configuration.rst | 2 +- .../{ => admin}/configuration/index.rst | 0 .../{ => admin}/configuration/policy.rst | 0 .../configuration/samples/index.rst | 0 .../configuration/samples/policy-yaml.rst | 2 +- doc/source/admin/index.rst | 7 ++- doc/source/{ => admin}/install/index.rst | 0 .../{ => admin}/install/install-rdo.rst | 0 .../{ => admin}/install/install-source.rst | 0 .../{ => admin}/install/install-ubuntu.rst | 0 doc/source/{ => admin}/install/mod_wsgi.rst | 2 +- .../{ => admin/quick_deployment}/devstack.rst | 3 +- doc/source/admin/quick_deployment/index.rst | 6 ++ doc/source/{ => admin}/sample_policy.rst | 0 doc/source/api-reference/index.rst | 9 +++ .../rating/hashmap.rst | 3 +- .../rating/pyscripts.rst | 3 +- doc/source/{webapi => api-reference}/root.rst | 0 doc/source/{webapi => api-reference}/v1.rst | 3 + doc/source/api.rst | 10 ---- doc/source/graph/arch.dot | 59 ------------------- doc/source/index.rst | 37 +++++++++--- doc/source/user/index.rst | 8 +++ .../{admin => user}/rating/graph/hashmap.dot | 0 doc/source/{admin => user}/rating/hashmap.rst | 0 doc/source/user/rating/index.rst | 10 ++++ .../{admin => user}/rating/introduction.rst | 0 .../{admin => user}/rating/pyscripts.rst | 0 29 files changed, 74 insertions(+), 90 deletions(-) rename doc/source/{arch.rst => admin/architecture.rst} (100%) rename doc/source/{ => admin}/configuration/configuration.rst (99%) rename doc/source/{ => admin}/configuration/index.rst (100%) rename doc/source/{ => admin}/configuration/policy.rst (100%) rename doc/source/{ => admin}/configuration/samples/index.rst (100%) rename doc/source/{ => admin}/configuration/samples/policy-yaml.rst (71%) rename doc/source/{ => admin}/install/index.rst (100%) rename doc/source/{ => admin}/install/install-rdo.rst (100%) rename doc/source/{ => admin}/install/install-source.rst (100%) rename doc/source/{ => admin}/install/install-ubuntu.rst (100%) rename doc/source/{ => admin}/install/mod_wsgi.rst (96%) rename doc/source/{ => admin/quick_deployment}/devstack.rst (91%) create mode 100644 doc/source/admin/quick_deployment/index.rst rename doc/source/{ => admin}/sample_policy.rst (100%) create mode 100644 doc/source/api-reference/index.rst rename doc/source/{webapi => api-reference}/rating/hashmap.rst (97%) rename doc/source/{webapi => api-reference}/rating/pyscripts.rst (90%) rename doc/source/{webapi => api-reference}/root.rst (100%) rename doc/source/{webapi => api-reference}/v1.rst (97%) delete mode 100644 doc/source/api.rst delete mode 100644 doc/source/graph/arch.dot create mode 100644 doc/source/user/index.rst rename doc/source/{admin => user}/rating/graph/hashmap.dot (100%) rename doc/source/{admin => user}/rating/hashmap.rst (100%) create mode 100644 doc/source/user/rating/index.rst rename doc/source/{admin => user}/rating/introduction.rst (100%) rename doc/source/{admin => user}/rating/pyscripts.rst (100%) diff --git a/doc/source/arch.rst b/doc/source/admin/architecture.rst similarity index 100% rename from doc/source/arch.rst rename to doc/source/admin/architecture.rst diff --git a/doc/source/configuration/configuration.rst b/doc/source/admin/configuration/configuration.rst similarity index 99% rename from doc/source/configuration/configuration.rst rename to doc/source/admin/configuration/configuration.rst index e54ae414..9e748c52 100644 --- a/doc/source/configuration/configuration.rst +++ b/doc/source/admin/configuration/configuration.rst @@ -125,7 +125,7 @@ without modifying source code or Cloudkitty configuration file. The ``/etc/cloudkitty/metrics.yml`` file looks like this: -.. literalinclude:: ../../../etc/cloudkitty/metrics.yml +.. literalinclude:: ../../../../etc/cloudkitty/metrics.yml :language: yaml Conversion information is included in the yaml file. diff --git a/doc/source/configuration/index.rst b/doc/source/admin/configuration/index.rst similarity index 100% rename from doc/source/configuration/index.rst rename to doc/source/admin/configuration/index.rst diff --git a/doc/source/configuration/policy.rst b/doc/source/admin/configuration/policy.rst similarity index 100% rename from doc/source/configuration/policy.rst rename to doc/source/admin/configuration/policy.rst diff --git a/doc/source/configuration/samples/index.rst b/doc/source/admin/configuration/samples/index.rst similarity index 100% rename from doc/source/configuration/samples/index.rst rename to doc/source/admin/configuration/samples/index.rst diff --git a/doc/source/configuration/samples/policy-yaml.rst b/doc/source/admin/configuration/samples/policy-yaml.rst similarity index 71% rename from doc/source/configuration/samples/policy-yaml.rst rename to doc/source/admin/configuration/samples/policy-yaml.rst index 266f1a20..4d3bfcb5 100644 --- a/doc/source/configuration/samples/policy-yaml.rst +++ b/doc/source/admin/configuration/samples/policy-yaml.rst @@ -5,4 +5,4 @@ policy.yaml Use the ``policy.yaml`` file to define additional access controls that apply to the Rating service: -.. literalinclude:: ../../_static/policy.yaml.sample +.. literalinclude:: ../../../_static/policy.yaml.sample diff --git a/doc/source/admin/index.rst b/doc/source/admin/index.rst index e42f2984..36192f8d 100644 --- a/doc/source/admin/index.rst +++ b/doc/source/admin/index.rst @@ -5,6 +5,7 @@ Administration Guide .. toctree:: :glob: - rating/introduction.rst - rating/hashmap.rst - rating/pyscripts.rst + architecture + quick_deployment/index + install/index + configuration/index diff --git a/doc/source/install/index.rst b/doc/source/admin/install/index.rst similarity index 100% rename from doc/source/install/index.rst rename to doc/source/admin/install/index.rst diff --git a/doc/source/install/install-rdo.rst b/doc/source/admin/install/install-rdo.rst similarity index 100% rename from doc/source/install/install-rdo.rst rename to doc/source/admin/install/install-rdo.rst diff --git a/doc/source/install/install-source.rst b/doc/source/admin/install/install-source.rst similarity index 100% rename from doc/source/install/install-source.rst rename to doc/source/admin/install/install-source.rst diff --git a/doc/source/install/install-ubuntu.rst b/doc/source/admin/install/install-ubuntu.rst similarity index 100% rename from doc/source/install/install-ubuntu.rst rename to doc/source/admin/install/install-ubuntu.rst diff --git a/doc/source/install/mod_wsgi.rst b/doc/source/admin/install/mod_wsgi.rst similarity index 96% rename from doc/source/install/mod_wsgi.rst rename to doc/source/admin/install/mod_wsgi.rst index 0f718c63..10051ed4 100644 --- a/doc/source/install/mod_wsgi.rst +++ b/doc/source/admin/install/mod_wsgi.rst @@ -35,7 +35,7 @@ etc/apache2/cloudkitty The ``etc/apache2/cloudkitty`` file contains example settings that work with a copy of cloudkitty installed via devstack. -.. literalinclude:: ../../../etc/apache2/cloudkitty +.. literalinclude:: ../../../../etc/apache2/cloudkitty 1. On deb-based systems copy or symlink the file to ``/etc/apache2/sites-available``. For rpm-based systems the file will go in diff --git a/doc/source/devstack.rst b/doc/source/admin/quick_deployment/devstack.rst similarity index 91% rename from doc/source/devstack.rst rename to doc/source/admin/quick_deployment/devstack.rst index 6725e710..329e090f 100644 --- a/doc/source/devstack.rst +++ b/doc/source/admin/quick_deployment/devstack.rst @@ -1,6 +1,5 @@ -##################### DevStack installation -##################### +===================== Add the following lines in your ``local.conf`` file to enable CloudKitty with gnocchi collector:: diff --git a/doc/source/admin/quick_deployment/index.rst b/doc/source/admin/quick_deployment/index.rst new file mode 100644 index 00000000..de663338 --- /dev/null +++ b/doc/source/admin/quick_deployment/index.rst @@ -0,0 +1,6 @@ +Quick Deployment +================ + +.. toctree:: + + devstack diff --git a/doc/source/sample_policy.rst b/doc/source/admin/sample_policy.rst similarity index 100% rename from doc/source/sample_policy.rst rename to doc/source/admin/sample_policy.rst diff --git a/doc/source/api-reference/index.rst b/doc/source/api-reference/index.rst new file mode 100644 index 00000000..bf4de08e --- /dev/null +++ b/doc/source/api-reference/index.rst @@ -0,0 +1,9 @@ +======================== +CloudKitty API reference +======================== + +.. toctree:: + :glob: + + root + v1 diff --git a/doc/source/webapi/rating/hashmap.rst b/doc/source/api-reference/rating/hashmap.rst similarity index 97% rename from doc/source/webapi/rating/hashmap.rst rename to doc/source/api-reference/rating/hashmap.rst index c24abbb0..88364042 100644 --- a/doc/source/webapi/rating/hashmap.rst +++ b/doc/source/api-reference/rating/hashmap.rst @@ -1,6 +1,5 @@ -======================= HashMap Module REST API -======================= +----------------------- .. rest-controller:: cloudkitty.rating.hash.controllers.root:HashMapConfigController :webprefix: /v1/rating/module_config/hashmap diff --git a/doc/source/webapi/rating/pyscripts.rst b/doc/source/api-reference/rating/pyscripts.rst similarity index 90% rename from doc/source/webapi/rating/pyscripts.rst rename to doc/source/api-reference/rating/pyscripts.rst index 8fd00883..20af7540 100644 --- a/doc/source/webapi/rating/pyscripts.rst +++ b/doc/source/api-reference/rating/pyscripts.rst @@ -1,6 +1,5 @@ -========================= PyScripts Module REST API -========================= +------------------------- .. rest-controller:: cloudkitty.rating.pyscripts.controllers.root:PyScriptsConfigController :webprefix: /v1/rating/module_config/pyscripts diff --git a/doc/source/webapi/root.rst b/doc/source/api-reference/root.rst similarity index 100% rename from doc/source/webapi/root.rst rename to doc/source/api-reference/root.rst diff --git a/doc/source/webapi/v1.rst b/doc/source/api-reference/v1.rst similarity index 97% rename from doc/source/webapi/v1.rst rename to doc/source/api-reference/v1.rst index 6977ad7f..d6900871 100644 --- a/doc/source/webapi/v1.rst +++ b/doc/source/api-reference/v1.rst @@ -67,6 +67,9 @@ Rating .. autotype:: cloudkitty.api.v1.datamodels.rating.CloudkittyResourceCollection :members: +.. include:: rating/hashmap.rst + +.. include:: rating/pyscripts.rst Report ====== diff --git a/doc/source/api.rst b/doc/source/api.rst deleted file mode 100644 index d4c2f17e..00000000 --- a/doc/source/api.rst +++ /dev/null @@ -1,10 +0,0 @@ -############# -API Reference -############# - -.. toctree:: - :glob: - - webapi/root - webapi/v1 - webapi/rating/* diff --git a/doc/source/graph/arch.dot b/doc/source/graph/arch.dot deleted file mode 100644 index d447e62e..00000000 --- a/doc/source/graph/arch.dot +++ /dev/null @@ -1,59 +0,0 @@ -digraph "CloudKitty's Architecture" { - - // Graph parameters - label="CloudKitty's Internal Architecture"; - node [shape=box]; - compound=true; - - // API - api [label="API"]; - - // Orchestrator - subgraph cluster_3 { - label="Orchestrator"; - node[shape=none, width=1.3, height=0, label=""]; - {rank=same; o1 -> o2 -> o3 [style=invis];} - } - - // Collector - ceilometer [label="Ceilometer"]; - vendor [label="Vendor specific", style=dotted]; - subgraph cluster_0 { - label="Collector"; - style=dashed; - ceilometer -> vendor [style=invis]; - } - - // Rating - hashmap [label="HashMap module"]; - r_others [label="Other modules...", style=dotted]; - subgraph cluster_1 { - label="Rating engines"; - style=dashed; - hashmap -> r_others [style=invis]; - } - - // Write Orchestrator - w_orchestrator [label="Write Orchestrator"]; - tdb [label="Transient DB"]; - - //Writers - osrf [label="OpenStack\nReference Format\n(json)"]; - w_others [label="Other modules...", style=dotted]; - subgraph cluster_2 { - label="Writers"; - style=dashed; - osrf -> w_others [style=invis]; - } - - // Relations - api -> hashmap; - api -> r_others; - o1 -> ceilometer [dir=both, ltail=cluster_3, lhead=cluster_0]; - o2 -> hashmap [dir=both, ltail=cluster_3, lhead=cluster_1]; - o3 -> w_orchestrator [ltail=cluster_3]; - w_orchestrator -> osrf [constraint=false]; - w_orchestrator -> w_others [style=dotted, constraint=false]; - w_orchestrator -> tdb; -} - diff --git a/doc/source/index.rst b/doc/source/index.rst index 12a50590..9a441752 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -10,13 +10,32 @@ Welcome to CloudKitty's documentation! CloudKitty is a Rating As A Service project aimed at translating metrics to prices. -.. toctree:: - :maxdepth: 2 +.. list-table:: + :header-rows: 1 - install/index - configuration/index - admin/index - developer/index - devstack - arch - api + * - Documentation type + - Table of contents + + * - **End User** + - .. toctree:: + :maxdepth: 2 + + user/index + + * - **Admin / Operator** + - .. toctree:: + :maxdepth: 2 + + admin/index + + * - **Developer** + - .. toctree:: + :maxdepth: 2 + + developer/index + + * - **API Reference** + - .. toctree:: + :maxdepth: 2 + + api-reference/index diff --git a/doc/source/user/index.rst b/doc/source/user/index.rst new file mode 100644 index 00000000..41f4879c --- /dev/null +++ b/doc/source/user/index.rst @@ -0,0 +1,8 @@ +================== +User documentation +================== + +.. toctree:: + :maxdepth: 2 + + rating/index diff --git a/doc/source/admin/rating/graph/hashmap.dot b/doc/source/user/rating/graph/hashmap.dot similarity index 100% rename from doc/source/admin/rating/graph/hashmap.dot rename to doc/source/user/rating/graph/hashmap.dot diff --git a/doc/source/admin/rating/hashmap.rst b/doc/source/user/rating/hashmap.rst similarity index 100% rename from doc/source/admin/rating/hashmap.rst rename to doc/source/user/rating/hashmap.rst diff --git a/doc/source/user/rating/index.rst b/doc/source/user/rating/index.rst new file mode 100644 index 00000000..9bff6c93 --- /dev/null +++ b/doc/source/user/rating/index.rst @@ -0,0 +1,10 @@ +====== +Rating +====== + +.. toctree:: + :glob: + + introduction.rst + hashmap.rst + pyscripts.rst diff --git a/doc/source/admin/rating/introduction.rst b/doc/source/user/rating/introduction.rst similarity index 100% rename from doc/source/admin/rating/introduction.rst rename to doc/source/user/rating/introduction.rst diff --git a/doc/source/admin/rating/pyscripts.rst b/doc/source/user/rating/pyscripts.rst similarity index 100% rename from doc/source/admin/rating/pyscripts.rst rename to doc/source/user/rating/pyscripts.rst