Repository :
http://git.fedorahosted.org/cgit/cura-tools.git
On branch : master
---------------------------------------------------------------
commit fdd587cffef87ffad8d4a37edce4ade6737558aa
Author: Michal Minar <miminar(a)redhat.com>
Date: Thu Dec 11 10:18:01 2014 +0100
docs: generate docs for openlmi-scripts pkg for epel
EPEL openlmi-scripts contains just metacommand and scripts common
library. Therefore its documentation shall contain the same.
Fallback to using openlmitheme - when generating docs for scripts in
epel.
Use exported COMMANDS variable in build-with-sphinx helper instead of
generating its own.
---------------------------------------------------------------
doc/Makefile | 3 +-
doc/src/Makefile | 15 +++++++++-
doc/src/build-with-sphinx.sh | 5 +++-
doc/src/conf.py.skel | 25 +++++++++++++----
doc/src/genapi.sh | 62 ++++++++++++++++++++++++++++++-----------
doc/src/index-scripts.txt | 15 ++++++++++
6 files changed, 98 insertions(+), 27 deletions(-)
diff --git a/doc/Makefile b/doc/Makefile
index 8218f64..a4babf6 100644
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -5,13 +5,14 @@ SPHINXOPTS =
SPHINXBUILD := sphinx-build
PAPER =
BUILDDIR ?= build
+JUST_SCRIPTS ?= 0
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
+export JUST_SCRIPTS WITH_COMMANDS OPENLMI_SCRIPTS_DIR
# Internal variables.
PAPEROPT_a4 = -D latex_paper_size=a4
diff --git a/doc/src/Makefile b/doc/src/Makefile
index 35db676..9e3c580 100644
--- a/doc/src/Makefile
+++ b/doc/src/Makefile
@@ -5,16 +5,20 @@ BUILDDIR ?= ../build
SPHINXBUILD ?= sphinx-build
SRCDIR ?= ../../cli
PROJECTNAME := OpenLMITools
+JUST_SCRIPTS ?= 0
WITH_COMMANDS ?= 0
ifeq ($(WITH_COMMANDS), 1)
TAGS := $(TAGS) -t with-commands
COMMANDS ?= $(notdir $(shell find $(OPENLMI_SCRIPTS_DIR)/commands -mindepth 1 \
-maxdepth 1 -type d | sort))
endif
+ifeq ($(JUST_SCRIPTS), 1)
+ TAGS := $(TAGS) -t just-scripts
+endif
ALLSPHINXOPTS ?= -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
ALLSPHINXOPTS := $(TAGS) $(ALLSPHINXOPTS)
-export WITH_COMMANDS OPENLMI_SCRIPTS_DIR COMMANDS
+export JUST_SCRIPTS WITH_COMMANDS OPENLMI_SCRIPTS_DIR COMMANDS
.PHONY: clean deps
@@ -47,12 +51,16 @@ index-%: subindexes-%
echo " :maxdepth: $$DEPTH"; \
echo ""; \
echo " metacommand-index"; \
+ if [ "$JUST_SCRIPTS" != 0 ]; then \
echo " shell-index"; \
+ fi; \
if [ "$*" == html -o "$*" == rtd ]; then \
echo " api"; \
fi; \
) > toc.txt
- if [[ "$*" =~ ^(html|rtd)$$ ]]; then \
+ if [[ "$$JUST_SCRIPTS" == 1 ]]; then \
+ ln -sf index-scripts.txt index.rst; \
+ elif [[ "$*" =~ ^(html|rtd)$$ ]]; then \
ln -sf index-$*.txt index.rst; \
else \
ln -sf index-other.txt index.rst; \
@@ -65,6 +73,8 @@ subindexes-%: shell-index-% metacommand-index-% api-%
@echo "Built subindexes for $* build."
shell-index-%:
+ @echo "Making shell index for $* build."
+ifeq ($(JUST_SCRIPTS), 0)
( \
case "$*" in \
html) DEPTH=1; ;; \
@@ -98,6 +108,7 @@ shell-index-%:
echo " shell/interactive_interface"; \
echo " shell/builtins"; \
) > shell-index.rst
+endif
metacommand-index-man:
@echo "Skipping metacommand documentation"
diff --git a/doc/src/build-with-sphinx.sh b/doc/src/build-with-sphinx.sh
index 9532df1..3e8aaa2 100755
--- a/doc/src/build-with-sphinx.sh
+++ b/doc/src/build-with-sphinx.sh
@@ -25,7 +25,10 @@ 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
+ if [[ -z "$COMMANDS" ]]; then
+ COMMANDS=`find . -maxdepth 1 -mindepth 1 -type d | sort`
+ fi
+ for cmd in $COMMANDS; do
pushd $cmd
python setup.py develop --install-dir=$tmp
popd
diff --git a/doc/src/conf.py.skel b/doc/src/conf.py.skel
index bf8cb08..e1ccd0a 100644
--- a/doc/src/conf.py.skel
+++ b/doc/src/conf.py.skel
@@ -110,8 +110,9 @@ if os.path.isfile(path + "/objects.inv"):
local_inventory = path + "/objects.inv"
intersphinx_mapping = {'http://docs.openlmi.org/en/latest': local_inventory}
-# Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
+if not tags.has('just-scripts'):
+ # Add any paths that contain templates here, relative to this directory.
+ templates_path = ['_templates']
# The suffix of source filenames.
source_suffix = '.rst'
@@ -124,6 +125,8 @@ master_doc = 'index'
# General information about the project.
project = 'OpenLMI Tools'
+if tags.has('just-scripts'):
+ project = 'OpenLMI Scripts'
copyright = '2012-2014, Red Hat Inc.'
# The version info for the project you're documenting, acts as replacement for
@@ -150,8 +153,10 @@ release = '@@VERSION@@'
exclude_patterns = ['scripts/commands/**/index.rst']
if tags.has('man-build'):
exclude_patterns.append('scripts')
-elif tags.has('html-build'):
+elif tags.has('html-build') and not tags.has('just-scripts'):
exclude_patterns.append('shell/man_page.rst')
+if tags.has('just-scripts'):
+ exclude_patterns.append('shell/*')
# The reST default role (used for this markup: `text`) to use for all documents.
#default_role = None
@@ -179,9 +184,17 @@ pygments_style = 'sphinx'
on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
if not on_rtd: # only import and set the theme if we're building docs locally
- import sphinx_rtd_theme
- html_theme = 'sphinx_rtd_theme'
- html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+ try:
+ import sphinx_rtd_theme
+ html_theme = 'sphinx_rtd_theme'
+ html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+ except ImportError:
+ if tags.has('just-scripts'):
+ # Fallback to openlmi theme if we build scripts doc for epel
+ html_theme = 'openlmitheme'
+ else:
+ # OpenLMI Tools shall have rtd theme
+ raise
# The name for this set of Sphinx documents. If None, it defaults to
# "<project> v<release> documentation".
diff --git a/doc/src/genapi.sh b/doc/src/genapi.sh
index 02e634a..95df2b0 100755
--- a/doc/src/genapi.sh
+++ b/doc/src/genapi.sh
@@ -6,6 +6,7 @@ TOPDIR=../..
DOCDIR=$TOPDIR/doc/src
SRCDIR=$TOPDIR/cli/lmi
WITH_COMMANDS=${WITH_COMMANDS:-0}
+JUST_SCRIPTS=${JUST_SCRIPTS:-0}
function get_modules() {
pushd "$SRCDIR/$1" >/dev/null
@@ -24,7 +25,9 @@ function get_module_name() {
function get_version_string() {
pushd $TOPDIR/cli >/dev/null
- out=`python setup.py --version`
+ setup=setup.py
+ [ $JUST_SCRIPTS = 1 ] && setup=setup-scripts.py
+ out=`python $setup --version`
git_version=`git describe HEAD 2>/dev/null`
echo -n "\`\`$out\`\`"
if [ -n "$git_version" ]; then
@@ -37,13 +40,17 @@ function get_scripts_version_string() {
cat $OPENLMI_SCRIPTS_DIR/VERSION 2>/dev/null
}
-for dir in shell scripts/common; do
+declare -a gendirs
+[ $JUST_SCRIPTS = 0 ] && gendirs+=("shell")
+gendirs+=("scripts/common")
+for dir in ${gendirs[@]}; do
[ -e $DOCDIR/api/$dir ] || mkdir -p $DOCDIR/api/$dir
[ -e $DOCDIR/api/$dir ] || mkdir -p $DOCDIR/api/$dir
done
# api.rst header
-cat >$DOCDIR/api.rst <<_EOF_
+if [[ $JUST_SCRIPTS = 0 ]]; then
+ cat >$DOCDIR/api.rst <<_EOF_
OpenLMI Tools API reference
===========================
@@ -61,6 +68,25 @@ Generated from version: $(get_version_string)
api/shell
api/scripts
_EOF_
+else
+ cat >$DOCDIR/api.rst <<_EOF_
+OpenLMI Scripts API reference
+=============================
+
+This is a generated documentation from *OpenLMI Scripts* sources.
+
+Generated from version: $(get_version_string)
+
+.. only:: html
+
+ **Contents:**
+
+.. toctree::
+ :maxdepth: 2
+
+ api/scripts
+_EOF_
+fi
cat >$DOCDIR/api/shell.rst <<_EOF_
LMIShell API reference
@@ -134,24 +160,26 @@ Generated from version: $(get_version_string)
_EOF_
-# Generate api/shell/*.rst
-for module_path in `get_modules shell`; do
- if [[ "$module_path" =~ ^compat ]]; then
- continue
- fi
- module=`echo "$module_path" | get_module_name`
- len=`echo $module | wc -c`
- len=$(($len-1))
- underline=""
- for i in `seq $len`; do underline="=$underline"; done
- echo >>$DOCDIR/api/shell.rst " shell/$module"
- cat >$DOCDIR/api/shell/${module}.rst <<-_EOF_
+if [[ $JUST_SCRIPTS = 0 ]]; then
+ # Generate api/shell/*.rst
+ for module_path in `get_modules shell`; do
+ if [[ "$module_path" =~ ^compat ]]; then
+ continue
+ fi
+ module=`echo "$module_path" | get_module_name`
+ len=`echo $module | wc -c`
+ len=$(($len-1))
+ underline=""
+ for i in `seq $len`; do underline="=$underline"; done
+ echo >>$DOCDIR/api/shell.rst " shell/$module"
+ cat >$DOCDIR/api/shell/${module}.rst <<-_EOF_
$module
$underline
.. automodule:: lmi.shell.$module
:members:
_EOF_
-done
+ done
+fi
# Generate api/scripts/common/*.rst
for module_path in `get_modules scripts/common`; do
@@ -170,7 +198,7 @@ for module_path in `get_modules scripts/common`; do
done
# Add commands api reference to api/scripts.rst
-if [ $WITH_COMMANDS = 1 ]; then
+if [[ $WITH_COMMANDS = 1 ]]; then
if [ -z "$COMMANDS" ]; then
COMMANDS=`find $OPENLMI_SCRIPTS_DIR/commands \
-mindepth 1 -maxdepth 1 -type d | sort | xargs basename -a`
diff --git a/doc/src/index-scripts.txt b/doc/src/index-scripts.txt
new file mode 100644
index 0000000..915de7a
--- /dev/null
+++ b/doc/src/index-scripts.txt
@@ -0,0 +1,15 @@
+OpenLMI Scripts documentation
+=============================
+
+OpenLMI Scripts comproses of *LMI Meta-command* and a collection of small
+python libraries with command-line wrappers.
+
+.. warning::
+ *LMI Meta-command* has been moved into *OpenLMI Tools*, where it logically
+ belongs, in version 0.2.8. Feature releases of `openlmi-scripts` package
+ on RHEL will lack this application as well. This package will be just a
+ collection of scripts.
+
+**Contents:**
+
+.. include:: toc.txt