Merge pull request #365 from splunk/fix-docs-gen

Fix duplicate TOC in Sphinx docs and automate bundling of docs

Author: fantavlik

Makefile

@@ -28,6 +28,14 @@ build_app:
 	@echo "$(ATTN_COLOR)==> build_app $(NO_COLOR)"
 	@python setup.py build dist
 
+.PHONY: docs
+docs:
+	@echo "$(ATTN_COLOR)==> docs $(NO_COLOR)"
+	@rm -rf ./docs/_build
+	@tox -e docs
+	@cd ./docs/_build/html && zip -r ../docs_html.zip . -x ".*" -x "__MACOSX"
+	@echo "$(ATTN_COLOR)==> Docs pages can be found at ./docs/_build/html, docs bundle available at ./docs/_build/docs_html.zip"
+
 .PHONY: test
 test:
 	@echo "$(ATTN_COLOR)==> test $(NO_COLOR)"

docs/conf.py

@@ -138,7 +138,7 @@
 # Custom sidebar templates, maps document names to template names.
 #html_sidebars = {
 html_sidebars = {
-   '**': ['localtoc.html', 'globaltoc.html', 'searchbox.html'],
+   '**': ['globaltoc.html', 'searchbox.html'],
 }
 
 # Additional templates that should be rendered to pages, maps page names to

tox.ini

@@ -1,5 +1,5 @@
 [tox]
-envlist = clean,py27,py37
+envlist = clean,docs,py27,py37
 skipsdist = {env:TOXBUILD:false}
 
 [testenv:pep8]
@@ -26,7 +26,7 @@ application-import-names = splunk-sdk-python
 passenv = LANG
 setenv = SPLUNK_HOME=/opt/splunk
          INPUT_EXAMPLE_UPLOAD=/opt/splunk/var/log/splunk/splunkd_ui_access.log
-whitelist_externals = true
+allowlist_externals = make
 deps = pytest
        pytest-cov
        xmlrunner
@@ -41,3 +41,9 @@ commands =
 deps = coverage
 skip_install = true
 commands = coverage erase
+
+[testenv:docs]
+description = invoke sphinx-build to build the HTML docs
+basepython = python3.7
+deps = sphinx >= 1.7.5, < 2
+commands = make -C docs/ html