Automate the generation of api docs toctree

Create a script to generate/update the api docs toctree and run it
whenever `make docs-html` is run.

Close #126

docs/Makefile

@@ -18,6 +18,7 @@ clean-api-docs:
 gen-api-docs: clean-api-docs
 	@sphinx-apidoc -efMT -o api ../camayoc
 	@sphinx-apidoc -efMT -o api ../tests
+	@../scripts/gen_api_docs.sh
 
 html: gen-api-docs
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/api.rst

@@ -7,47 +7,56 @@ 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
-    api/camayoc.tests.remote.rst
-    api/camayoc.tests.remote.rho.test_scan.rst
-    api/camayoc.api.rst
-    api/camayoc.qcs_models.rst
-    api/camayoc.tests.qcs.rst
-    api/camayoc.tests.qcs.conftest.rst
-    api/camayoc.tests.qcs.api.rst
-    api/camayoc.tests.qcs.api.v1.rst
-    api/camayoc.tests.qcs.api.v1.authentication.test_login.rst
-    api/camayoc.tests.qcs.api.v1.credentials.test_network_creds.rst
-    api/camayoc.tests.qcs.api.v1.credentials.test_manager_creds.rst
-    api/camayoc.tests.qcs.api.v1.credentials.test_creds_common.rst
-    api/camayoc.tests.qcs.api.v1.reports.test_reports.rst
-    api/camayoc.tests.qcs.api.v1.scans.test_network_scans.rst
-    api/camayoc.tests.qcs.api.v1.scans.test_satellite_scans.rst
-    api/camayoc.tests.qcs.api.v1.scans.test_vcenter_scans.rst
-    api/camayoc.tests.qcs.api.v1.scans.test_multi_source_scans.rst
-    api/camayoc.tests.qcs.api.v1.sources.test_network_sources.rst
-    api/camayoc.tests.qcs.api.v1.sources.test_manager_sources.rst
-    api/camayoc.tests.qcs.api.v1.sources.test_sources_common.rst
-    api/camayoc.tests.qcs.cli.test_credentials.rst
-    api/camayoc.tests.qcs.cli.test_scans.rst
-    api/camayoc.tests.qcs.cli.test_sources.rst
-    api/camayoc.tests.qcs.cli.utils.rst
-    api/camayoc.tests.qcs.cli.conftest.rst
-    api/camayoc.tests.qcs.cli.utils.rst
+    api/camayoc
+    api/camayoc.api
+    api/camayoc.cli
+    api/camayoc.config
+    api/camayoc.constants
+    api/camayoc.exceptions
+    api/camayoc.qcs_models
+    api/camayoc.tests
+    api/camayoc.tests.conftest
+    api/camayoc.tests.qcs
+    api/camayoc.tests.qcs.api
+    api/camayoc.tests.qcs.api.v1
+    api/camayoc.tests.qcs.api.v1.authentication
+    api/camayoc.tests.qcs.api.v1.authentication.test_login
+    api/camayoc.tests.qcs.api.v1.credentials
+    api/camayoc.tests.qcs.api.v1.credentials.test_creds_common
+    api/camayoc.tests.qcs.api.v1.credentials.test_manager_creds
+    api/camayoc.tests.qcs.api.v1.credentials.test_network_creds
+    api/camayoc.tests.qcs.api.v1.reports
+    api/camayoc.tests.qcs.api.v1.reports.test_reports
+    api/camayoc.tests.qcs.api.v1.scans
+    api/camayoc.tests.qcs.api.v1.scans.test_multi_source_scans
+    api/camayoc.tests.qcs.api.v1.scans.test_network_scans
+    api/camayoc.tests.qcs.api.v1.scans.test_satellite_scans
+    api/camayoc.tests.qcs.api.v1.scans.test_vcenter_scans
+    api/camayoc.tests.qcs.api.v1.sources
+    api/camayoc.tests.qcs.api.v1.sources.test_manager_sources
+    api/camayoc.tests.qcs.api.v1.sources.test_network_sources
+    api/camayoc.tests.qcs.api.v1.sources.test_sources_common
+    api/camayoc.tests.qcs.api.v1.utils
+    api/camayoc.tests.qcs.cli
+    api/camayoc.tests.qcs.cli.conftest
+    api/camayoc.tests.qcs.cli.test_credentials
+    api/camayoc.tests.qcs.cli.test_scans
+    api/camayoc.tests.qcs.cli.test_sources
+    api/camayoc.tests.qcs.cli.utils
+    api/camayoc.tests.qcs.conftest
+    api/camayoc.tests.qcs.utils
+    api/camayoc.tests.remote
+    api/camayoc.tests.remote.rho
+    api/camayoc.tests.remote.rho.test_scan
+    api/camayoc.tests.rho
+    api/camayoc.tests.rho.test_auth
+    api/camayoc.tests.rho.test_fact
+    api/camayoc.tests.rho.test_options
+    api/camayoc.tests.rho.test_profile
+    api/camayoc.tests.rho.test_scan
+    api/camayoc.tests.rho.utils
+    api/camayoc.utils
+    api/tests
+    api/tests.test_api
+    api/tests.test_cli
+    api/tests.test_config

scripts/gen_api_docs.sh

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+#
+# For each file found by `find`, generate a entry on the toctree in
+# `docs/api.rst`.
+#
+# NOTE: This script should be run from the repository docs directory. That is,
+# this script should be run from this script's ../docs directory.
+
+set -euo pipefail
+
+# Recreate the api toctree document with its header
+cat >"api.rst" <<EOF
+API Documentation
+=================
+
+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::
+
+EOF
+
+# List every rst file on the toctree
+find api -type f -name '*.rst' | sed "s/.rst$//" | sort | while read file_name; do
+    echo "    ${file_name}" >>"api.rst"
+done