Updates after becoming an official projects

* Build documentation on docs.openstack.org
* Add badges, update README
* Adjust docs subdirs to match the standards

Change-Id: Ie4f51f994ef783c4924a6523fbdfe600fede6d12

.gitignore

@@ -6,7 +6,8 @@
 
 # Sphinx
 _build
-doc/source/api/
+doc/source/reference/api/
+doc/source/.doctrees/
 
 # Packages/installer info
 *.egg

.zuul.yaml

@@ -174,9 +174,7 @@
       - openstack-python36-jobs
       - openstack-lower-constraints-jobs
       - openstack-cover-jobs
-      - docs-on-readthedocs
+      - publish-openstack-docs-pti
-    vars:
-      rtd_webhook_id: '37378'
     check:
       jobs:
         - metalsmith-integration-glance-localboot-centos7

README.rst

@@ -1,19 +1,22 @@
 Deployment and Scheduling tool for Bare Metal
 =============================================
 
+.. image:: https://governance.openstack.org/badges/metalsmith.svg
+    :target: https://governance.openstack.org/reference/tags/index.html
+
 Overview
 --------
 
 This is a simple tool to provision bare metal machines using `OpenStack Bare
-Metal Service (ironic) <https://docs.openstack.org/ironic/latest/>`_,
+Metal Service (ironic) <https://docs.openstack.org/ironic/latest/>`_ and,
-`OpenStack Image Service (glance) <https://docs.openstack.org/glance/latest/>`_
+optionally, `OpenStack Image Service (glance)
-and `OpenStack Networking Service (neutron)
+<https://docs.openstack.org/glance/latest/>`_ and `OpenStack Networking
-<https://docs.openstack.org/neutron/latest/>`_.
+Service (neutron) <https://docs.openstack.org/neutron/latest/>`_.
 
 * License: Apache License, Version 2.0
-* Documentation: https://metalsmith.readthedocs.io
+* Documentation: https://docs.openstack.org/metalsmith/
 * Source: https://git.openstack.org/cgit/openstack/metalsmith
-* Bugs: https://storyboard.openstack.org/#!/project/1000
+* Bugs: https://storyboard.openstack.org/#!/project/openstack/metalsmith
 
 Installation
 ------------
@@ -22,30 +25,6 @@ Installation
 
     pip install --user metalsmith
 
-CLI Usage
----------
-
-Generic usage is as follows::
-
-    metalsmith --os-cloud <CLOUD NAME> deploy --image <GLANCE IMAGE> \
-        --network <NEUTRON NET> --ssh-public-key <PATH TO SSH PUBLIC KEY> \
-        --resource-class <RESOURCE CLASS>
-
-This is an example suitable for TripleO (replace ``compute`` with the profile
-you want to deploy)::
-
-    source ~/stackrc
-    metalsmith deploy --image overcloud-full --network ctlplane \
-        --capability profile=compute --ssh-public-key ~/.ssh/id_rsa.pub \
-        --resource-class baremetal
-
-To remove the deployed instance::
-
-    metalsmith --os-cloud <CLOUD NAME> undeploy <NODE UUID>
-
-For all possible options see the built-in help::
-
-    metalsmith --help
 
 Contributing
 ------------
@@ -55,5 +34,5 @@ Contributing
   (see `developer's guide
   <https://docs.openstack.org/infra/manual/developers.html>`_)
 * Bugs and RFEs:  `StoryBoard
-  <https://storyboard.openstack.org/#!/project/1000>`_
+  <https://storyboard.openstack.org/#!/project/openstack/metalsmith>`_
   (please do NOT report bugs to Github)

doc/requirements.txt

@@ -3,3 +3,4 @@
 # process, which may cause wedges in the gate later.
 sphinx!=1.6.6,!=1.6.7,>=1.6.2 # BSD
 sphinxcontrib-apidoc>=0.2.0  # BSD
+openstackdocstheme>=1.18.1 # Apache-2.0

doc/source/cli/index.rst

@@ -0,0 +1,33 @@
+metalsmith CLI
+==============
+
+Deploy Command
+--------------
+
+Generic usage is as follows::
+
+    metalsmith --os-cloud <CLOUD NAME> deploy --image <GLANCE IMAGE> \
+        --network <NEUTRON NET> --ssh-public-key <PATH TO SSH PUBLIC KEY> \
+        --resource-class <RESOURCE CLASS>
+
+This is an example suitable for TripleO (replace ``compute`` with the profile
+you want to deploy)::
+
+    source ~/stackrc
+    metalsmith deploy --image overcloud-full --network ctlplane \
+        --capability profile=compute --ssh-public-key ~/.ssh/id_rsa.pub \
+        --resource-class baremetal
+
+Undeploy Command
+----------------
+
+To remove the deployed instance::
+
+    metalsmith --os-cloud <CLOUD NAME> undeploy <NODE UUID>
+
+See Also
+--------
+
+For all possible options see the built-in help::
+
+    metalsmith --help

doc/source/conf.py

@@ -23,9 +23,15 @@ extensions = [
     'sphinxcontrib.apidoc',
 ]
 
+try:
+    import openstackdocstheme
+    extensions.append('openstackdocstheme')
+except ImportError:
+    openstackdocstheme = None
+
 autoclass_content = 'both'
 apidoc_module_dir = '../../metalsmith'
-apidoc_output_dir = 'api'
+apidoc_output_dir = 'reference/api'
 apidoc_excluded_paths = ['test']
 apidoc_separate_modules = True
 
@@ -71,6 +77,11 @@ pygments_style = 'sphinx'
 # html_theme = '_theme'
 # html_static_path = ['static']
 
+if openstackdocstheme is not None:
+    html_theme = 'openstackdocs'
+else:
+    html_theme = 'default'
+
 # Output file base name for HTML help builder.
 htmlhelp_basename = '%sdoc' % project
 

doc/source/index.rst

@@ -8,12 +8,20 @@ The main entry point to the API is :py:class:`metalsmith.Provisioner`.
 .. toctree::
    :maxdepth: 3
 
-   api/metalsmith
+   reference/api/metalsmith
 
 .. toctree::
    :hidden:
 
-   api/modules
+   reference/api/modules
+
+Command-Line Interface
+----------------------
+
+.. toctree::
+   :maxdepth: 2
+
+   cli/index
 
 Ansible Role
 ------------

tox.ini

@@ -26,6 +26,7 @@ commands =
   coverage combine
   coverage report -m --fail-under 90
   coverage html -d ./cover --omit='*test*'
+  coverage xml -o cover/coverage.xml
 
 [testenv:venv]
 deps =