Improve docs

* Move all document source into the doc/source directory.
* Normalize sections to follow conventions used in [Python’s Style Guide
  for
  documenting][http://www.sphinx-doc.org/en/stable/rest.html#sections].

CONTRIBUTING.rst

@@ -76,7 +76,7 @@ Adding Facts
 If you want to make a change that affects the documentation of
 particular facts,
 
-1. Make the change in `doc/command_syntax_usage.rst`
+1. Make the change in `doc/source/command_syntax_usage.rst`
 2. Run `make gen-python-docs` to update `rho/fact_docs.py`
 3. Check in the new version of `rho/fact_docs.py` with your change
 

README.rst

@@ -3,7 +3,6 @@
 .. image:: https://coveralls.io/repos/github/quipucords/rho/badge.svg
     :target: https://coveralls.io/github/quipucords/rho
 
-
 ====================================================================
    rho - Tool for discovering RHEL, Linux, and Unix Servers
 ====================================================================
@@ -183,7 +182,7 @@ rho manpage with other usage examples. The common options are listed with the
 examples in this document.
 
 For expanded information on auth entries, profiles, scanning, and output read
-the `syntax and usage document <doc/command_syntax_usage.rst>`_.
+the `syntax and usage document <doc/source/command_syntax_usage.rst>`_.
 
 -----------------------
 Development
@@ -238,7 +237,7 @@ Functional Testing
 """""""""""""""""""
 
 To run end-to-end functional tests against local virtual machines follow the
-information in `functional test document <doc/functional_test.rst>`_.
+information in `functional test document <doc/source/functional_test.rst>`_.
 
 
 -------------

doc/command_example.rst → doc/source/command_example.rst

@@ -1,6 +1,5 @@
-^^^^^^^^^^^^^^^^^
 Example rho Scan
-^^^^^^^^^^^^^^^^^
+=================
 
 Following is the results of an example rho scan. This is the example of the
 profile called 'big_test' and it's host auth mapping utilizing the cached
@@ -19,7 +18,7 @@ The following files are created but are encrypted using the rho vault password p
 
 
 Example Host Auth Mapping
-""""""""""""""""""""""""""
+-------------------------
 
 ::
 
@@ -56,7 +55,7 @@ Example Host Auth Mapping
 
 
 Facts
-"""""""
+-----
 The facts collected were:
 
 - uname.hostname
@@ -68,7 +67,7 @@ The facts collected were:
 - redhat-packages.num_installed_packages
 
 Example Output
-""""""""""""""""
+--------------
 
 ::
 

doc/command_syntax_usage.rst → doc/source/command_syntax_usage.rst

@@ -1,6 +1,6 @@
------------------------
 Command Syntax & Usage
------------------------
+======================
+
 The basic syntax is:
 
 ``rho command subcommand [options]``
@@ -26,19 +26,18 @@ The complete list of options for each command and subcommand are listed in the
 rho manpage with other usage examples. The common options are listed with the
 examples in this document.
 
-^^^^^^^^^^^^^
 Auth Entries
-^^^^^^^^^^^^^
+------------
+
 The first step to configuring rho is adding auth credentials to use to connect
 over SSH. Each authentication identity requires its own auth entry.
 
 ``rho auth add --name=server1creds --username=rho-user --sshkeyfile=/etc/ssh/ssh_host_rsa_key``
 
 *Note:* --password not being passed or passed as empty are considered the same thing.
 
--------------------------
 SSH Key with a Passphrase
--------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^
 
 There are two ways to handle ssh keys with passphrases. If a
 passphrase-protected ssh key is specified in an auth and the key is
@@ -50,9 +49,9 @@ agent (as documented at
 http://docs.ansible.com/ansible/latest/intro_getting_started.html),
 which will decrypt them once and make them available to Rho.
 
-^^^^^^^^^
 Profiles
-^^^^^^^^^
+---------
+
 Then, create the profile to use for the scan. This should include a list of IP
 addresses or ranges, and the auth identity to use.
 
@@ -68,9 +67,9 @@ where ``hosts_file`` contains the ip address or ranges separated by newlines::
   1.2.3.14
   1.2.4.34
 
-^^^^^^^^^
 Scanning
-^^^^^^^^^
+--------
+
 The options required for a scan are the profile to use and the file path for
 the report. Optionally we can pass the number of Ansible forks and the facts to
 be collected. Finally the ``cache`` option tells rho that the profile you are
@@ -100,18 +99,17 @@ The output of the Ansible process is saved to `$XDG_DATA_HOME/rho/scan_log` by
 default, for debugging. This location can be changed with the
 `--logfile` flag.
 
-^^^^^^^^^^^^
 Common Flags
-^^^^^^^^^^^^
+------------
 
 All rho commands accept the `-v` flag, which increases the verbosity
 of rho's output. It comes in four varieties: `-v`, `-vv`, `-vvv`, and
 `-vvvv`, with more `v`'s indicating more verbose output. The verbose
 output can be useful in debugging.
 
-^^^^^^^
 Output
-^^^^^^^
+------
+
 The important part about a scan is the results report. By default,
 this contains a large amount of information about the operating system, hardware, and platform.
 
@@ -186,9 +184,9 @@ of 'default' will get all the information listed above.
 For further details of the command usage view the following
 `example <command_example.rst>`_.
 
-^^^^^^^^^^^^^^^^^^^^^
 Scan User Permissions
-^^^^^^^^^^^^^^^^^^^^^
+---------------------
+
 Some of the output facts will report an error if the user used to perform the
 scan does not have the appropriate permissions to execute the command used to
 gather the targeted facts. The following set of facts require *admin/root*
@@ -218,11 +216,10 @@ If the scan user uses a password to sudo, one can be given with the
 commands. The sudo-with-password fundtionality can be tested by using
 the 'askpass' box in the Vagrantfile.
 
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
 Programs on Remote Machines
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
+---------------------------
 
 Besides standard Unix utilities, some rho fact collectors depend on
 specific programs being installed on the machines being scanned. The
 complete list is at `remote programs
-<github.com/quipucords/rho/doc/remote_programs.rst>`_.
+<github.com/quipucords/rho/doc/source/remote_programs.rst>`_.

doc/source/conf.py

@@ -98,7 +98,7 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+# html_static_path = ['_static']
 
 # Custom sidebar templates, must be a dictionary that maps document names
 # to template names.

doc/functional_test.rst → doc/source/functional_test.rst

@@ -1,6 +1,5 @@
------------------------
 Functional Testing
------------------------
+==================
 
 The nature of ``rho`` tool is to discover and scan remote systems. In order
 to test this feature locally we need to employ tools to allow us to simulate
@@ -9,9 +8,9 @@ a remote environment. We will be utilizing
 `Virtual Box <https://www.virtualbox.org/wiki/VirtualBox>`_ along with Ansible
 to create and initialize several virtual systems.
 
-^^^^^^^^^^^^^^^^^^^^^^^^
 Installing Dependencies
-^^^^^^^^^^^^^^^^^^^^^^^^
+-----------------------
+
 *Virtual Box*
 
 For OS X you can go to the
@@ -47,9 +46,8 @@ the Centos 64-bit RPM. Then install with::
   rpm -ivh <package>.rpm
 
 
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 Provisioning Virtual Systems
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+----------------------------
 
 From the root directory of the local repository you will see a file named
 `Vagrantfile` which specifies three systems that will be setup and initialized
@@ -59,9 +57,8 @@ directory. Run the following command to provision the systems::
   vagrant up
 
 
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 Note: testing on RHEL
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+---------------------
 
 The Vagrantfile assumes the existance of a Vagrant box called
 `rhel-server-7-1`. You can make a RHEL box by following one of the
@@ -72,9 +69,9 @@ https://developers.redhat.com/blog/2016/06/06/using-vagrant-to-get-started-with-
 If you don't want to test with RHEL, you can replace that box name
 with a different one, such as `centos/7`.
 
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 Executing rho on Test Bed
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+-------------------------
+
 You should have three virtual systems running with the following IP Address:
 - 192.168.50.10
 - 192.168.50.11

doc/source/index.rst

@@ -10,7 +10,10 @@ Welcome to rho's documentation!
    :maxdepth: 2
    :caption: Contents:
 
-
+   command_example
+   command_syntax_usage
+   remote_programs
+   functional_test
 
 Indices and tables
 ==================

doc/remote_programs.rst → doc/source/remote_programs.rst

@@ -1,6 +1,5 @@
----------------
 Remote Programs
----------------
+===============
 
 This file documents which programs on the remote host are used to
 collect different groups of facts. **bold** is used for executables