From 9b81016f4347a45e6b4ff019ec047ca6726f04e5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ely=C3=A9zer=20Rezende?= Date: Fri, 8 Sep 2017 10:33:28 -0300 Subject: [PATCH] Improve docs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * 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 | 2 +- README.rst | 5 ++-- doc/{ => source}/command_example.rst | 9 +++--- doc/{ => source}/command_syntax_usage.rst | 35 +++++++++++------------ doc/source/conf.py | 2 +- doc/{ => source}/functional_test.rst | 17 +++++------ doc/source/index.rst | 5 +++- doc/{ => source}/remote_programs.rst | 3 +- 8 files changed, 36 insertions(+), 42 deletions(-) rename doc/{ => source}/command_example.rst (95%) rename doc/{ => source}/command_syntax_usage.rst (96%) rename doc/{ => source}/functional_test.rst (91%) rename doc/{ => source}/remote_programs.rst (97%) diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 50d95ec..66ded90 100644 --- a/CONTRIBUTING.rst +++ b/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 diff --git a/README.rst b/README.rst index 8eb27c5..a354b7a 100644 --- a/README.rst +++ b/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 `_. +the `syntax and usage document `_. ----------------------- 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 `_. +information in `functional test document `_. ------------- diff --git a/doc/command_example.rst b/doc/source/command_example.rst similarity index 95% rename from doc/command_example.rst rename to doc/source/command_example.rst index 1175a72..ca3be0d 100644 --- a/doc/command_example.rst +++ b/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 -"""""""""""""""" +-------------- :: diff --git a/doc/command_syntax_usage.rst b/doc/source/command_syntax_usage.rst similarity index 96% rename from doc/command_syntax_usage.rst rename to doc/source/command_syntax_usage.rst index a0e1e2f..e1b40f2 100644 --- a/doc/command_syntax_usage.rst +++ b/doc/source/command_syntax_usage.rst @@ -1,6 +1,6 @@ ------------------------ Command Syntax & Usage ------------------------ +====================== + The basic syntax is: ``rho command subcommand [options]`` @@ -26,9 +26,9 @@ 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. @@ -36,9 +36,8 @@ over SSH. Each authentication identity requires its own auth entry. *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 `_. -^^^^^^^^^^^^^^^^^^^^^ 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 -`_. +`_. diff --git a/doc/source/conf.py b/doc/source/conf.py index 5101608..ac219f4 100644 --- a/doc/source/conf.py +++ b/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. diff --git a/doc/functional_test.rst b/doc/source/functional_test.rst similarity index 91% rename from doc/functional_test.rst rename to doc/source/functional_test.rst index 5b8df37..39e783f 100644 --- a/doc/functional_test.rst +++ b/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 `_ 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 .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 diff --git a/doc/source/index.rst b/doc/source/index.rst index bf4e381..4bca4d3 100644 --- a/doc/source/index.rst +++ b/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 ================== diff --git a/doc/remote_programs.rst b/doc/source/remote_programs.rst similarity index 97% rename from doc/remote_programs.rst rename to doc/source/remote_programs.rst index c93284d..6391080 100644 --- a/doc/remote_programs.rst +++ b/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