Repository :
http://git.fedorahosted.org/cgit/cura-tools.git
On branch : master
---------------------------------------------------------------
commit d56ebe998d3530b373750ab96281948efe0f1462
Author: Michal Minar <miminar(a)redhat.com>
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/openlmit...
+[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