docs(readme): move to `docs/` directory and modify accordingly

README.rst → docs/README.rst

@@ -1,122 +1,152 @@
-======
+.. _readme:
+
 apache
 ======
 
+|img_travis| |img_sr|
+
+.. |img_travis| image:: https://travis-ci.com/saltstack-formulas/apache-formula.svg?branch=master
+   :alt: Travis CI Build Status
+   :scale: 100%
+   :target: https://travis-ci.com/saltstack-formulas/apache-formula
+.. |img_sr| image:: https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg
+   :alt: Semantic Release
+   :scale: 100%
+   :target: https://github.com/semantic-release/semantic-release
+
 Formulas to set up and configure the Apache HTTP server.
 
-.. note::
+.. contents:: **Table of Contents**
+
+General notes
+-------------
+
+See the full `SaltStack Formulas installation and usage instructions
+<https://docs.saltstack.com/en/latest/topics/development/conventions/formulas.html>`_.
+
+If you are interested in writing or contributing to formulas, please pay attention to the `Writing Formula Section
+<https://docs.saltstack.com/en/latest/topics/development/conventions/formulas.html#writing-formulas>`_.
+
+If you want to use this formula, please pay attention to the ``FORMULA`` file and/or ``git tag``,
+which contains the currently released version. This formula is versioned according to `Semantic Versioning <http://semver.org/>`_.
 
-    See the full `Salt Formulas installation and usage instructions
-    <http://docs.saltstack.com/en/latest/topics/development/conventions/formulas.html>`_.
+See `Formula Versioning Section <https://docs.saltstack.com/en/latest/topics/development/conventions/formulas.html#versioning>`_ for more details.
+
+Contributing to this repo
+-------------------------
+
+**Commit message formatting is significant!!**
+
+Please see `How to contribute <https://github.com/saltstack-formulas/.github/blob/master/CONTRIBUTING.rst>`_ for more details.
 
 Available states
-================
+----------------
 
 .. contents::
-    :local:
+   :local:
 
 ``apache``
-----------
+^^^^^^^^^^
 
 Installs the Apache package and starts the service.
 
 ``apache.config``
------------------
+^^^^^^^^^^^^^^^^^
 
 Configures apache based on os_family
 
 ``apache.certificates``
------------------
+^^^^^^^^^^^^^^^^^^^^^^^
 
 Deploy SSL certificates from pillars
 
 ``apache.mod_mpm``
-------------------
+^^^^^^^^^^^^^^^^^^
 
 Configures the apache mpm modules on Debian ``mpm_prefork``, ``mpm_worker`` or ``mpm_event`` (Debian Only)
 
 ``apache.modules``
-------------------
+^^^^^^^^^^^^^^^^^^
 
 Enables and disables Apache modules.
 
 ``apache.mod_rewrite``
-----------------------
+^^^^^^^^^^^^^^^^^^^^^^
 
 Enabled the Apache module mod_rewrite (Debian and FreeBSD only)
 
 ``apache.mod_proxy``
--------------------
+^^^^^^^^^^^^^^^^^^^^
 
 Enables the Apache module mod_proxy. (Debian and FreeBSD only)
 
 ``apache.mod_proxy_http``
--------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Enables the Apache module mod_proxy_http and requires the Apache module mod_proxy to be enabled. (Debian Only)
 
 ``apache.mod_proxy_fcgi``
--------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Enables the Apache module mod_proxy_fcgi and requires the Apache module mod_proxy to be enabled. (Debian Only)
 
 ``apache.mod_wsgi``
--------------------
+^^^^^^^^^^^^^^^^^^^
 
 Installs the mod_wsgi package and enables the Apache module.
 
 ``apache.mod_actions``
-----------------------
+^^^^^^^^^^^^^^^^^^^^^^
 
 Enables the Apache module mod_actions. (Debian Only)
 
 ``apache.mod_headers``
-----------------------
+^^^^^^^^^^^^^^^^^^^^^^
 
 Enables the Apache module mod_headers. (Debian Only)
 
 ``apache.mod_pagespeed``
-------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^
 
 Installs and Enables the mod_pagespeed module. (Debian and RedHat Only)
 
 ``apache.mod_perl2``
--------------------
+^^^^^^^^^^^^^^^^^^^^
 
 Installs and enables the mod_perl2 module (Debian and FreeBSD only)
 
 ``apache.mod_geoip``
--------------------
+^^^^^^^^^^^^^^^^^^^^
 
 Installs and enables the mod_geoIP (RedHat only)
 
 ``apache.mod_php5``
--------------------
+^^^^^^^^^^^^^^^^^^^
 
 Installs and enables the mod_php5 module
 
 ``apache.mod_cgi``
----------------------
+^^^^^^^^^^^^^^^^^^
 
 Enables mod_cgi. (FreeBSD only)
 
 ``apache.mod_fcgid``
---------------------
+^^^^^^^^^^^^^^^^^^^^
 
 Installs and enables the mod_fcgid module (Debian only)
 
 ``apache.mod_fastcgi``
---------------------
+^^^^^^^^^^^^^^^^^^^^^^
 
 Installs and enables the mod_fastcgi module
 
 ``apache.mod_dav_svn``
---------------------
+^^^^^^^^^^^^^^^^^^^^^^
 
 Installs and enables the mod_dav_svn module (Debian only)
 
 ``apache.mod_security``
-----------------------
+^^^^^^^^^^^^^^^^^^^^^^^
 
 Installs an enables the `Apache mod_security2 WAF`<http://modsecurity.org/>`_
 using data from Pillar. (Debian and RedHat Only)
@@ -124,53 +154,53 @@ using data from Pillar. (Debian and RedHat Only)
 Allows you to install the basic Core Rules (CRS) and some basic configuration for mod_security2
 
 ``apache.mod_security.rules``
------------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 This state can create symlinks based on basic Core Rules package. (Debian only)
 Or it can distribute a mod_security rule file and place it /etc/modsecurity/
 
 ``apache.mod_socache_shmcb``
----------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Enables mod_socache_shmcb. (FreeBSD only)
 
 ``apache.mod_ssl``
-----------------------
+^^^^^^^^^^^^^^^^^^
 
 Installs and enables the mod_ssl module (Debian, RedHat and FreeBSD only)
 
 ``apache.mod_suexec``
----------------------
+^^^^^^^^^^^^^^^^^^^^^
 
 Enables mod_suexec. (FreeBSD only)
 
 ``apache.mod_vhost_alias``
-----------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Enables the Apache module vhost_alias (Debian Only)
 
 ``apache.mod_remoteip``
-----------------------
+^^^^^^^^^^^^^^^^^^^^^^^
 
 Enables and configures the Apache module mod_remoteip using data from Pillar. (Debian Only)
 
 ``apache.mod_xsendfile``
-----------------------
+^^^^^^^^^^^^^^^^^^^^^^^^
 
 Installs and enables mod_xsendfile module. (Debian Only)
 
 ``apache.own_default_vhost``
---------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Replace default vhost with own version. By default, it's 503 code. (Debian Only)
 
 ``apache.no_default_vhost``
---------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Remove the default vhost. (Debian Only)
 
 ``apache.vhosts.standard``
---------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Configures Apache name-based virtual hosts and creates virtual host directories using data from Pillar.
 
@@ -194,22 +224,22 @@ of interfaces to bind to. For example, to bind both IPv4 and IPv6:
           interface: '1.2.3.4 [2001:abc:def:100::3]'
 	  
 ``apache.manage_security``
---------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Configures Apache's security.conf options by reassinging them using data from Pillar.
 
 ``apache.server_status``
---------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^
 
 Configures Apache's server_status handler for localhost
 
 ``apache.debian_full``
-----------------------
+^^^^^^^^^^^^^^^^^^^^^^
 
 Installs and configures Apache on Debian and Ubuntu systems.
 
 ``apache.uninstall``
-----------
+^^^^^^^^^^^^^^^^^^^^
 
 Stops the Apache service and uninstalls the package.
 
@@ -238,3 +268,48 @@ Example Pillar:
           name: 'my name'
           path: 'salt://path/to/sites-available/conf/file'
           state: 'enabled'
+
+Testing
+-------
+
+Linux testing is done with ``kitchen-salt``.
+
+Requirements
+^^^^^^^^^^^^
+
+* Ruby
+* Docker
+
+.. code-block:: bash
+
+   $ gem install bundler
+   $ bundle install
+   $ bin/kitchen test [platform]
+
+Where ``[platform]`` is the platform name defined in ``kitchen.yml``,
+e.g. ``debian-9-2019-2-py3``.
+
+``bin/kitchen converge``
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+Creates the docker instance and runs the ``template`` main state, ready for testing.
+
+``bin/kitchen verify``
+^^^^^^^^^^^^^^^^^^^^^^
+
+Runs the ``inspec`` tests on the actual instance.
+
+``bin/kitchen destroy``
+^^^^^^^^^^^^^^^^^^^^^^^
+
+Removes the docker instance.
+
+``bin/kitchen test``
+^^^^^^^^^^^^^^^^^^^^
+
+Runs all of the stages above in one go: i.e. ``destroy`` + ``converge`` + ``verify`` + ``destroy``.
+
+``bin/kitchen login``
+^^^^^^^^^^^^^^^^^^^^^
+
+Gives you SSH access to the instance for manual testing.