Repository : http://git.fedorahosted.org/cgit/cura-tools.git
On branch : master
commit fdd587cffef87ffad8d4a37edce4ade6737558aa Author: Michal Minar miminar@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
cura-tools-devel@lists.fedorahosted.org