Add API docs

Make sure all modules are added into documentation under the API docs.

Update docs Makefile and config to make sure the build fails on warnings
and the API docs RST documents are generated whenever the documentation
is built.

Closes #19

camayoc/config.py

@@ -28,7 +28,6 @@ def get_config():
     configuration object is returned.
 
     :returns: A copy of the global server configuration object.
-    :rtype: dict
     """
     global _CONFIG  # pylint:disable=global-statement
     if _CONFIG is None:

camayoc/tests/rho/test_auth.py

@@ -73,7 +73,7 @@ def test_add_with_username_password_sudo_password(isolated_filesystem):
     :description: Add an auth entry providing the ``--name``, ``--username``,
         ``--pasword`` and ``--sudo-password`` options.
     :steps: Run ``rho auth add --name <name> --username <username> --password
-    --sudo-password``
+        --sudo-password``
     :expectedresults: A new auth entry is created with the data provided as
         input.
     """
@@ -374,7 +374,7 @@ def test_edit_password_negative(isolated_filesystem):
     :id: 3469c05d-2dee-4b5a-84a8-e9f3ce391480
     :description: Edit the password of a not created auth entry.
     :steps: Run ``rho auth edit --name <invalidname> --password
-    <newpassword>``
+        <newpassword>``
     :expectedresults: The command should fail with a proper message.
     """
     name = utils.uuid4()
@@ -469,7 +469,7 @@ def test_edit_sshkeyfile_negative(isolated_filesystem):
     :id: 4c43d7af-5dd8-4a97-8d48-9cd2e611844e
     :description: Edit the sshkeyfile of a not created auth entry.
     :steps: Run ``rho auth edit --name <invalidname> --sshkeyfile
-    <newsshkeyfile>``
+        <newsshkeyfile>``
     :expectedresults: The command should fail with a proper message.
     """
     name = utils.uuid4()
@@ -605,7 +605,7 @@ def test_edit_no_credentials(isolated_filesystem):
     :description: Edit any field of a not created auth entry when no
         credentials where privously created.
     :steps: Run ``rho auth edit --name <invalidname> --sshkeyfile
-    <sshkeyfile>``
+        <sshkeyfile>``
     :expectedresults: The command should fail with a proper message.
     """
     name = utils.uuid4()

camayoc/tests/rho/test_profile.py

@@ -683,7 +683,7 @@ def test_clear_no_profiles(isolated_filesystem, option):
     :steps:
         1. Ensure an empty RHO data dir
         2. Run ``rho profile clear --name <name>`` or ``rho profile clear
-            --all``.
+           --all``.
     :expectedresults: A message stating that all network profiles were removed.
     """
     if option == '--name':

camayoc/tests/rho/utils.py

@@ -13,7 +13,7 @@ def input_vault_password(process, vault_password=VAULT_PASSWORD):
 
     :param process: A pexpect object returned by the ``pexpect.spawn``.
     :param vault_password: The vault password to be used, defaults to
-        :ref:`camayoc.constants.VAULT_PASSWORD`.
+        :data:`camayoc.constants.VAULT_PASSWORD`.
     """
     assert process.expect(VAULT_PASSWORD_INPUT) == 0
     process.sendline(vault_password)
@@ -29,7 +29,7 @@ def auth_add(
         filled.
     :param exitstatus: Expected exit status code.
     :param vault_password: The vault password to be used, defaults to
-        :ref:`camayoc.constants.VAULT_PASSWORD`.
+        :data:`camayoc.constants.VAULT_PASSWORD`.
     """
     command = 'rho auth add'
     for key, value in options.items():

docs/Makefile

@@ -2,7 +2,7 @@
 #
 
 # You can set these variables from the command line.
-SPHINXOPTS    =
+SPHINXOPTS    = -W
 SPHINXBUILD   = python -msphinx
 SPHINXPROJ    = Camayoc
 SOURCEDIR     = .
@@ -12,9 +12,12 @@ BUILDDIR      = _build
 help:
 	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
-.PHONY: help Makefile
+gen-api-docs:
+	cd ..; ./scripts/gen_api_docs.sh
+
+.PHONY: gen-api-docs help Makefile
 
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
-%: Makefile
-	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+%: gen-api-docs Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/api.rst

@@ -0,0 +1,29 @@
+API Documentation
+=================
+
+Location: :doc:`/index` → :doc:`/api`
+
+This is the Camayoc API documentation. It is mostly auto generated from the
+source code. This section of the documentation should be treated as a handy
+reference for developers, not a gospel.
+
+.. toctree::
+
+    api/camayoc.rst
+    api/camayoc.cli.rst
+    api/camayoc.config.rst
+    api/camayoc.constants.rst
+    api/camayoc.exceptions.rst
+    api/camayoc.tests.conftest.rst
+    api/camayoc.tests.rho.rst
+    api/camayoc.tests.rho.test_auth.rst
+    api/camayoc.tests.rho.test_fact.rst
+    api/camayoc.tests.rho.test_options.rst
+    api/camayoc.tests.rho.test_profile.rst
+    api/camayoc.tests.rho.test_scan.rst
+    api/camayoc.tests.rho.utils.rst
+    api/camayoc.tests.rst
+    api/camayoc.utils.rst
+    api/tests.rst
+    api/tests.test_cli.rst
+    api/tests.test_config.rst

docs/api/camayoc.cli.rst

@@ -0,0 +1,6 @@
+`camayoc.cli`
+=============
+
+Location: :doc:`/index` → :doc:`/api` → :doc:`/api/camayoc.cli`
+
+.. automodule:: camayoc.cli

docs/api/camayoc.config.rst

@@ -0,0 +1,6 @@
+`camayoc.config`
+================
+
+Location: :doc:`/index` → :doc:`/api` → :doc:`/api/camayoc.config`
+
+.. automodule:: camayoc.config

docs/api/camayoc.constants.rst

@@ -0,0 +1,6 @@
+`camayoc.constants`
+===================
+
+Location: :doc:`/index` → :doc:`/api` → :doc:`/api/camayoc.constants`
+
+.. automodule:: camayoc.constants

docs/api/camayoc.exceptions.rst

@@ -0,0 +1,6 @@
+`camayoc.exceptions`
+====================
+
+Location: :doc:`/index` → :doc:`/api` → :doc:`/api/camayoc.exceptions`
+
+.. automodule:: camayoc.exceptions

docs/api/camayoc.rst

@@ -0,0 +1,6 @@
+`camayoc`
+=========
+
+Location: :doc:`/index` → :doc:`/api` → :doc:`/api/camayoc`
+
+.. automodule:: camayoc

docs/api/camayoc.tests.conftest.rst

@@ -0,0 +1,6 @@
+`camayoc.tests.conftest`
+========================
+
+Location: :doc:`/index` → :doc:`/api` → :doc:`/api/camayoc.tests.conftest`
+
+.. automodule:: camayoc.tests.conftest

docs/api/camayoc.tests.rho.rst

@@ -0,0 +1,6 @@
+`camayoc.tests.rho`
+===================
+
+Location: :doc:`/index` → :doc:`/api` → :doc:`/api/camayoc.tests.rho`
+
+.. automodule:: camayoc.tests.rho

docs/api/camayoc.tests.rho.test_auth.rst

@@ -0,0 +1,6 @@
+`camayoc.tests.rho.test_auth`
+=============================
+
+Location: :doc:`/index` → :doc:`/api` → :doc:`/api/camayoc.tests.rho.test_auth`
+
+.. automodule:: camayoc.tests.rho.test_auth

docs/api/camayoc.tests.rho.test_fact.rst

@@ -0,0 +1,6 @@
+`camayoc.tests.rho.test_fact`
+=============================
+
+Location: :doc:`/index` → :doc:`/api` → :doc:`/api/camayoc.tests.rho.test_fact`
+
+.. automodule:: camayoc.tests.rho.test_fact

docs/api/camayoc.tests.rho.test_options.rst

@@ -0,0 +1,6 @@
+`camayoc.tests.rho.test_options`
+================================
+
+Location: :doc:`/index` → :doc:`/api` → :doc:`/api/camayoc.tests.rho.test_options`
+
+.. automodule:: camayoc.tests.rho.test_options

docs/api/camayoc.tests.rho.test_profile.rst

@@ -0,0 +1,6 @@
+`camayoc.tests.rho.test_profile`
+================================
+
+Location: :doc:`/index` → :doc:`/api` → :doc:`/api/camayoc.tests.rho.test_profile`
+
+.. automodule:: camayoc.tests.rho.test_profile

docs/api/camayoc.tests.rho.test_scan.rst

@@ -0,0 +1,6 @@
+`camayoc.tests.rho.test_scan`
+=============================
+
+Location: :doc:`/index` → :doc:`/api` → :doc:`/api/camayoc.tests.rho.test_scan`
+
+.. automodule:: camayoc.tests.rho.test_scan

docs/api/camayoc.tests.rho.utils.rst

@@ -0,0 +1,6 @@
+`camayoc.tests.rho.utils`
+=========================
+
+Location: :doc:`/index` → :doc:`/api` → :doc:`/api/camayoc.tests.rho.utils`
+
+.. automodule:: camayoc.tests.rho.utils

docs/api/camayoc.tests.rst

@@ -0,0 +1,6 @@
+`camayoc.tests`
+===============
+
+Location: :doc:`/index` → :doc:`/api` → :doc:`/api/camayoc.tests`
+
+.. automodule:: camayoc.tests

docs/api/camayoc.utils.rst

@@ -0,0 +1,6 @@
+`camayoc.utils`
+===============
+
+Location: :doc:`/index` → :doc:`/api` → :doc:`/api/camayoc.utils`
+
+.. automodule:: camayoc.utils

docs/api/tests.rst

@@ -0,0 +1,6 @@
+`tests`
+=======
+
+Location: :doc:`/index` → :doc:`/api` → :doc:`/api/tests`
+
+.. automodule:: tests

docs/api/tests.test_cli.rst

@@ -0,0 +1,6 @@
+`tests.test_cli`
+================
+
+Location: :doc:`/index` → :doc:`/api` → :doc:`/api/tests.test_cli`
+
+.. automodule:: tests.test_cli

docs/api/tests.test_config.rst

@@ -0,0 +1,6 @@
+`tests.test_config`
+===================
+
+Location: :doc:`/index` → :doc:`/api` → :doc:`/api/tests.test_config`
+
+.. automodule:: tests.test_config

docs/conf.py

@@ -30,13 +30,15 @@
 
 # General configuration -------------------------------------------------------
 
+autodoc_default_flags = ['members']
 exclude_patterns = ['_build']
 extensions = [
     'sphinx.ext.autodoc',
     'sphinx.ext.viewcode',
 ]
 language = None
 master_doc = 'index'
+nitpicky = True
 pygments_style = 'sphinx'
 source_suffix = '.rst'
 templates_path = ['_templates']

docs/index.rst

@@ -1,11 +1,12 @@
-Welcome to Camayoc's documentation!
-===================================
+Camayoc
+=======
 
 .. toctree::
    :maxdepth: 2
    :caption: Contents:
 
    test_scenarios
+   api
 
 Indices and tables
 ==================

scripts/gen_api_docs.sh

@@ -0,0 +1,31 @@
+#!/usr/bin/env bash
+#
+# For each file found by `find`, generate a reStructuredText document in
+# `docs/api/`.
+#
+# NOTE: This script should be run from the repository root directory. That is,
+# this script should be run from this script's parent directory.
+#
+set -euo pipefail
+
+find camayoc/ tests/ -type f -name '*.py' | while read file_name; do
+    # Transform file names to python module names. For example:
+    #
+    #     tests/__init__.py → tests
+    #     tests/test_api.py → tests.test_api
+    #
+    # Note that file_name has no leading "./", as we omit it in find, above.
+    module_name="${file_name%.py}"
+    module_name="${module_name%/__init__}"
+    module_name="${module_name//\//.}"
+
+    # Generate stub *.rst file. (Tip: ${#foo} returns the length of foo.)
+    cat >"docs/api/${module_name}.rst" <<EOF
+\`${module_name}\`
+$(printf %${#module_name}s | tr ' ' =)==
+
+Location: :doc:\`/index\` → :doc:\`/api\` → :doc:\`/api/${module_name}\`
+
+.. automodule:: ${module_name}
+EOF
+done