New Ansible style docs layout (#2415)

* Add new "livereload" testenv for docs hacking This is the only way to edit the documentation. * Shorten badge title to fit smaller screen widths * Configure theme for aesthetics * Propose a new documentation layout This closes aligns with Ansible docs. * Provisionally align docs with new layout
ansible · Oct 28, 2019 · 0674ab3 · 0674ab3
1 parent 85af6bd
commit 0674ab3
Show file tree

Hide file tree

Showing 10 changed files with 102 additions and 32 deletions.
diff --git a/CHANGELOG.rst b/CHANGELOG.rst
@@ -1,6 +1,6 @@
-*******
-History
-*******
+*********
+Changelog
+*********
 
 Unreleased
 ==========

diff --git a/README.rst b/README.rst
@@ -1,6 +1,6 @@
-********
-Molecule
-********
+****************
+Ansible Molecule
+****************
 
 .. image:: https://badge.fury.io/py/molecule.svg
    :target: https://badge.fury.io/py/molecule
@@ -10,7 +10,7 @@ Molecule
    :target: https://molecule.readthedocs.io/en/stable/
    :alt: Documentation Status
 
-.. image:: https://img.shields.io/travis/com/ansible/molecule/master.svg?label=Linux%20builds%20%40%20Travis%20CI
+.. image:: https://img.shields.io/travis/com/ansible/molecule/master.svg?label=CI
    :target: https://travis-ci.com/ansible/molecule
 
 .. image:: https://img.shields.io/badge/code%20style-black-000000.svg
@@ -29,6 +29,9 @@ Molecule
    :target: LICENSE
    :alt: Repository License
 
+About Ansible Molecule
+======================
+
 Molecule is designed to aid in the development and testing of
 `Ansible`_ roles.
 

diff --git a/docs/conf.py b/docs/conf.py
@@ -151,7 +151,12 @@
 # further.  For a list of options available for each theme, see the
 # documentation.
 # html_theme_options = {}
-html_theme_options = {'analytics_id': 'UA-128382387-1'}
+html_theme_options = {
+    'collapse_navigation': False,
+    'analytics_id': 'UA-128382387-1',
+    'style_nav_header_background': 'white',
+    'style_external_links': True,
+}
 
 # Add any paths that contain custom themes here, relative to this directory.
 # html_theme_path = []

diff --git a/docs/examples.rst b/docs/examples.rst
@@ -1,6 +1,6 @@
-********
-Examples
-********
+*************************
+Common Molecule Use Cases
+*************************
 
 .. _docker-usage-example:
 

diff --git a/docs/getting-started.rst b/docs/getting-started.rst
@@ -4,6 +4,8 @@
 Getting Started Guide
 *********************
 
+If you're looking to move a little faster, see the :ref:`quick-start`.
+
 The following guide will step through an example of developing and testing a
 new Ansible role. After reading this guide, you should be familiar with the
 basics of how to use Molecule and what it can offer.

diff --git a/docs/index.rst b/docs/index.rst
@@ -1,27 +1,61 @@
 .. include:: ../README.rst
   :end-before: _documentation
 
-Contents:
-=========
+Installation, Upgrade & Porting
+===============================
 
 .. toctree::
-   :maxdepth: 3
-
-   installation
-   getting-started
-   usage
-   examples
-   configuration
-   testing
-   contributing
-   development
-   changelog
-   authors
-   faq
-
-Indices and tables
+   :maxdepth: 1
+
+   Installation Guide <installation>
+   Upgrade Guide <upgrade>
+   Porting Guide <porting>
+
+Using Molecule
+==============
+
+.. toctree::
+   :maxdepth: 1
+
+   Quickstart Guide <quick-start>
+   Getting Started Guide <getting-started>
+   Command Line Reference <usage>
+   Configuration Guide <configuration>
+
+Common Molecule Use Cases
+=========================
+
+.. toctree::
+   :maxdepth: 1
+
+   Common Use Cases <examples>
+   Frequently Asked Questions <faq>
+
+Contributing to Molecule
+========================
+
+.. toctree::
+   :maxdepth: 1
+
+   Contribution Guide <contributing>
+   Developer Testing Guide <testing>
+   Developer Release Guide <development>
+   Credits <authors>
+
+Extending Molecule
 ==================
 
+TODO.
+
+References and Appendices
+=========================
+
 * :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+
+Roadmaps
+========
+
+.. toctree::
+   :maxdepth: 1
+
+   Changelog <changelog>
diff --git a/docs/quick-start.rst b/docs/quick-start.rst
@@ -0,0 +1,7 @@
+.. _quick-start:
+
+*****************
+Quick Start Guide
+*****************
+
+TODO.
diff --git a/docs/upgrade.rst b/docs/upgrade.rst
@@ -0,0 +1,7 @@
+.. _upgrade:
+
+*************
+Upgrade Guide
+*************
+
+TODO.
diff --git a/docs/usage.rst b/docs/usage.rst
@@ -1,5 +1,5 @@
-Usage
-=====
+Command Line Reference
+======================
 
 Check
 ^^^^^

diff --git a/tox.ini b/tox.ini
@@ -75,6 +75,18 @@ commands =
 extras =
     docs
 
+[testenv:doc-livereload]
+description = Invoke sphinx-autobuild to build and reload the HTML docs
+basepython = {[testenv:doc]basepython}
+passenv = {[testenv:doc]passenv}
+usedevelop = {[testenv:doc]usedevelop}
+commands =
+    python -m sphinx_autobuild docs/ "{toxworkdir}/docs_out"
+deps =
+    sphinx-autobuild>=0.7.1,<1.0
+extras =
+    docs
+
 [testenv:dockerfile]
 description = Tests validity of embedded Dockerfile template used by docker driver
 commands =