[cura-tools] master: doc: allow to build documentation with commands (d56ebe9)

Repository : http://git.fedorahosted.org/cgit/cura-tools.git

On branch  : master
>

commit d56ebe998d3530b373750ab96281948efe0f1462
Author: Michal Minar 
Date:   Fri Sep 12 12:21:43 2014 +0200

doc: allow to build documentation with commands

Use
        WITH_COMMANDS=1 make html
    to include documentation of commands from openlmi-scripts repository.
    Additional step is needed -- symlink at doc/openlmi-scripts pointing to
    your local copy of openlmi-scripts repository must be created.
>

doc/Makefile                 |   59 ++++++++++++++++++++++++++++------------
 doc/README.md                |   10 ++++++-
 doc/src/Makefile             |   12 ++++++--
 doc/src/build-with-sphinx.sh |   24 ++++++++++++++--
 doc/src/conf.py.skel         |   25 +++++++++++++++--
 doc/src/scripts/Makefile     |   61 ++++++++++++++++++++++++++++++++++++++---
 doc/src/scripts/usage.rst    |    8 +++++-
 7 files changed, 165 insertions(+), 34 deletions(-)

diff --git a/doc/Makefile b/doc/Makefile
index 57b85d4..8218f64 100644
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -1,16 +1,28 @@
-SPHINXOPTS   =
-SPHINXBUILD  = sphinx-build
-PAPER        =
-BUILDDIR    ?= build
+# Includes *setup* and *clean-setup* rules.
+include ../Makefile.inc
+
+SPHINXOPTS        =
+SPHINXBUILD      := sphinx-build
+PAPER             =
+BUILDDIR         ?= build
+WITH_COMMANDS    ?= 0
+ifneq ($(WITH_COMMANDS), 0)
+    OPENLMI_SCRIPTS_DIR := $(abspath $(shell readlink openlmi-scripts))
+endif
+
+export BUILDDIR := $(abspath $(BUILDDIR))
+export WITH_COMMANDS OPENLMI_SCRIPTS_DIR

# Internal variables.
 PAPEROPT_a4     = -D latex_paper_size=a4
 PAPEROPT_letter = -D latex_paper_size=letter
-ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) src
+PAPER          ?= a4
 # the i18n builder cannot share the environment and doctrees with the others
 I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) src

-.PHONY: help clean html dirhtml singlehtml epub latex latexpdf text man
+export PAPEROPT_a4 PAPEROPT_letter PAPER I18NSPHINXOPTS
+
+.PHONY: help clean html dirhtml singlehtml epub latex latexpdf text man check

help:
    @echo "Please use `make <target>' where <target> is one of"
@@ -23,37 +35,48 @@ help:
    @echo "  text       to make text files"
    @echo "  man        to make manual pages"

-deps:
-	make -C src
-
-clean:
+clean:  clean-setup
    make -C src clean
    -rm -rf $(BUILDDIR)/*

-html:
+check: setup
+ifneq ($(WITH_COMMANDS), 0)
+ifeq ($(shell [ -L openlmi-scripts ]; echo $$?), 1)
+	@echo "Please create 'openlmi-scripts' symbolic link pointing to your local"
+	@echo "copy of openlmi-scripts repository."
+	false
+endif
+ifeq ($(shell [ -d $(OPENLMI_SCRIPTS_DIR) ]; echo $$?), 1)
+	@echo "openlmi-scripts' target does not point to directory."
+	false
+endif
+endif
+	true
+
+html: check
    make -C src $@-build
    @echo "Build finished. The HTML pages are in $(BUILDDIR)/html."

-dirhtml:
+dirhtml: check
    make -C src $@-build

-singlehtml:
+singlehtml: check
    make -C src $@-build

-epub:
+epub: check
    make -C src $@-build

-latex:
+latex: check
    make -C src $@-build
    @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
    @echo "Run `make' in that directory to run these through (pdf)latex" \
          "(use `make latexpdf' here to do that automatically)."

-latexpdf: deps
+latexpdf: check
    make -C src $@-build

-text:
+text: check
    make -C src $@-build

-man:
+man: check
    make -C src $@-build
diff --git a/doc/README.md b/doc/README.md
index f17bd9b..3e98b88 100644
--- a/doc/README.md
+++ b/doc/README.md
@@ -32,7 +32,14 @@ just replace the `html` argument with prefered one.
 #### Without commands documentation
 This build is the preferred one for Python Hosted site.

-    make -C doc html
+    # run in this directory
+    make html
+
+#### With commands documentation
+This build includes documentation of [OpenLMI Scripts][].
+
+    ln -sf path/to/local/copy/of/openlmi-scripts openlmi-scripts
+    WITH_COMMANDS=1 make html

How to upload
 -------------
@@ -44,3 +51,4 @@ Then run:

[pythonhosted]: http://pythonhosted.org/openlmi-tools/index.html 
 [theme]:        https://fedorahosted.org/openlmi/browser/openlmi-providers/tools/openlmithem...
+[OpenLMI Scripts]: https://github.com/openlmi/openlmi-scripts
diff --git a/doc/src/Makefile b/doc/src/Makefile
index a4db2d0..4ec89fa 100644
--- a/doc/src/Makefile
+++ b/doc/src/Makefile
@@ -1,11 +1,14 @@
 # Includes *setup* and *clean-setup* rules.
 include ../../Makefile.inc

-BUILDDIR        = ../build
+BUILDDIR       ?= ../build
 SPHINXBUILD    ?=  sphinx-build
-ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+ALLSPHINXOPTS  ?= -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 SRCDIR         ?= ../../cli
 PROJECTNAME    := OpenLMITools
+WITH_COMMANDS  ?= 0
+
+export WITH_COMMANDS OPENLMI_SCRIPTS_DIR

.PHONY: clean deps

@@ -23,7 +26,7 @@ latexpdf-build: latex-build
    @echo "latexpdf build finished"

%-build: deps-% index-%
-	export SPHINXBUILD SRCDIR
+	export SPHINXBUILD SRCDIR WITH_COMMANDS OPENLMI_SCRIPTS_DIR
    ./build-with-sphinx.sh -b $* -t $*-build $(ALLSPHINXOPTS) $(BUILDDIR)/$*
    @echo "$* build finished. Output is in $(BUILDDIR)/$*."

@@ -113,6 +116,9 @@ metacommand-index-%:
        echo ""; \
        echo "    scripts/usage"; \
        echo "    scripts/configuration"; \
+	    if [ $(WITH_COMMANDS) != 0 ]; then \
+	    echo "    scripts/commands"; \
+	    fi; \
        echo "    scripts/development"; \
    ) > metacommand-index.rst

diff --git a/doc/src/build-with-sphinx.sh b/doc/src/build-with-sphinx.sh
index a07c420..9532df1 100755
--- a/doc/src/build-with-sphinx.sh
+++ b/doc/src/build-with-sphinx.sh
@@ -10,11 +10,29 @@

SPHINXBUILD=${SPHINXBUILD:-sphinx-build}
 SRCDIR="${SRCDIR:-../../cli}"
+WITH_COMMANDS="${WITH_COMMANDS:-0}"
+
+# exit upon error at once
+set -e
+
 tmp=`mktemp -d`
-pushd "$SRCDIR"
 export PYTHONPATH=$tmp
-python setup.py develop --install-dir=$tmp || exit 1
+
+pushd "$SRCDIR"
+python setup.py develop --install-dir=$tmp
 popd  # ..
+
+if [ "$WITH_COMMANDS" == 1 ]; then
+    echo "Installing commands"
+    pushd "$OPENLMI_SCRIPTS_DIR/commands"
+    find . -maxdepth 1 -mindepth 1 -type d | while read cmd; do
+        pushd $cmd
+        python setup.py develop --install-dir=$tmp
+        popd
+    done
+    popd
+fi
+
 echo "Running: ${SPHINXBUILD} $@"
-${SPHINXBUILD} "$@" || exit 1
+${SPHINXBUILD} "$@"
 rm -rf $tmp
diff --git a/doc/src/conf.py.skel b/doc/src/conf.py.skel
index 877955c..b5923f1 100644
--- a/doc/src/conf.py.skel
+++ b/doc/src/conf.py.skel
@@ -51,6 +51,8 @@ def process_signature(app, what, name, obj, options, signature, return_annotatio
     return (signature, return_annotation)

def setup(app):
+    # Register new option to include documentation for metacommand's commands
+    app.add_config_value('with_commands', False, 'env')
     # Register new option to include class list and class tree in index.rst
     app.add_config_value('includeClasses', 'True', True)
     # Register a very simple lexer for syntax highlighting of a shell samples
@@ -60,7 +62,9 @@ def setup(app):

app.connect("autodoc-process-signature", process_signature)

+
 includeClasses = True
+with_commands = False

# If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
@@ -69,6 +73,21 @@ SRCDIR = os.environ.get('SRCDIR', '../../cli/lmi')
 sys.path[0:0] = [os.path.abspath(os.path.join(SRCDIR, p)) for p in (
         'scripts', 'shell')]

+if tags.has('with-commands'):
+    scripts_path = os.environ.get('OPENLMI_SCRIPTS_DIR', '../openlmi-scripts')
+    commands = os.environ.get('COMMANDS', '')
+    commands_dir = os.path.join(scripts_path, 'commands')
+    if not commands:
+        commands = [  f for f in os.listdir(commands_dir)
+                   if os.isdir(os.path.join(commands_dir, f)) ]
+    if commands:
+       for i, cmd in enumerate(commands.split(',')):
+           sys.path.insert(2 + i,
+                os.path.join(os.path.abspath(commands_dir), cmd))
+
+    with_commands = True
+    del scripts_path, commands, commands_dir
+
 # -- General configuration -----------------------------------------------------

# If your documentation needs a minimal Sphinx version, state it here.
@@ -122,11 +141,11 @@ release = '@@VERSION@@'

# List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
-exclude_patterns = []
+exclude_patterns = ['scripts/commands/**/index.rst']
 if tags.has('man-build'):
-    exclude_patterns = ['scripts']
+    exclude_patterns.append('scripts')
 elif tags.has('html-build'):
-    exclude_patterns = ['shell/man_page.rst']
+    exclude_patterns.append('shell/man_page.rst')

# The reST default role (used for this markup: `text`) to use for all documents.
 #default_role = None
diff --git a/doc/src/scripts/Makefile b/doc/src/scripts/Makefile
index 716e35b..f612dc7 100644
--- a/doc/src/scripts/Makefile
+++ b/doc/src/scripts/Makefile
@@ -1,10 +1,20 @@
-COMMANDS         ?= account hardware journald logicalfile networking \
-		    powermanagement service software storage sssd system
+WITH_COMMANDS    ?= 0
+ifneq ($(WITH_COMMANDS), 0)
+    COMMANDS     := $(notdir $(shell find $(OPENLMI_SCRIPTS_DIR)/commands -mindepth 1 \
+	     -maxdepth 1 -type d | sort))
+else
+    COMMANDS     ?= account hardware journald logicalfile networking \
+			powermanagement service software storage sssd system
+endif
 BUILD            ?= html

-.PHONY: all devel clean devindex
+.PHONY: all devel clean devindex commands.txt commands.rst

+ifeq ($(WITH_COMMANDS), 0)
 all: devel commands.txt devindex
+else
+all: devel commands.txt commands.rst devindex
+endif

devindex:
    ( \
@@ -26,15 +36,56 @@ devel:
    make -C devel

commands.txt:
+ifeq ($(WITH_COMMANDS), 0)
    ( \
    for cmd in $(COMMANDS); do \
        printf "    * `openlmi-scripts-$${cmd}"; \
        printf " http://pythonhosted.org/openlmi-scripts-$${cmd}`_\n"; \
    done; \
-	) >> $@
+	) > $@
+else
+	( \
+	for cmd in $(COMMANDS); do \
+	    printf "    * :ref:`openlmi-scripts-$${cmd}`\n"; \
+	done; \
+	) > $@
+endif
+
+commands.rst:
+ifeq (,$(OPENLMI_SCRIPTS_DIR))
+	@echo "OPENLMI_SCRIPTS_DIR is unset!"
+	false
+else
+	echo "Commands" > $@
+	echo "========" >> $@
+	-[ -e commands ] && rm -rf commands
+	mkdir commands
+	echo "Usage and developer documentations for commands of *LMI metacommand*'s" >> $@
+	printf "\n.. toctree::\n" >> $@
+	printf "    :maxdepth: 2\n\n" >> $@
+	find $(OPENLMI_SCRIPTS_DIR)/commands -mindepth 1 -maxdepth 1 -type d | sort | \
+		while read cmdpath; \
+	do \
+	    cmd=$$(basename $$cmdpath); \
+	    printf "    commands/$$cmd\n" >> $@; \
+	    ln -s "$${cmdpath}/doc" commands/$${cmd}_docdir; \
+	    title="$${cmd^} command"; \
+	    length=`echo "$$title" | wc -c`; \
+	    ( \
+		printf ".. _openlmi-scripts-$${cmd}:\n\n"; \
+	        printf "$${title}\n"; \
+	        printf -- "!%.0s" `seq 2 $$length`; \
+	        printf "\n\n"; \
+		printf ".. toctree::\n    :maxdepth: 2\n\n"; \
+		printf "    $${cmd}_docdir/cmdline.rst\n"; \
+		printf "    $${cmd}_docdir/python\n\n"; \
+	    ) > commands/$${cmd}.rst; \
+	done
+endif

clean:
    make -C devel clean
-	-rm commands.txt development.rst
+	-rm commands.txt commands.rst development.rst
+	-rm -rf commands

diff --git a/doc/src/scripts/usage.rst b/doc/src/scripts/usage.rst
index 49db1a6..a9e4547 100644
--- a/doc/src/scripts/usage.rst
+++ b/doc/src/scripts/usage.rst
@@ -154,7 +154,13 @@ install the most up to date versions.

Documentation
 ~~~~~~~~~~~~~
-All the commands' documentation is available online:
+.. ifconfig:: with_commands
+
+    Check out documentation of currently implemented commands.
+
+.. ifconfig:: not with_commands
+
+    All the commands' documentation is available online:

.. include:: commands.txt