cura-tools-devel September 2014

cura-tools-devel@lists.fedorahosted.org

3 participants
13 discussions

[cura-tools] master: Reduce TOC-depth in readthedocs pages. (7eca07e)
by jsafrane＠fedoraproject.org 30 Sep '14

30 Sep '14

Repository : http://git.fedorahosted.org/cgit/cura-tools.git On branch : master >--------------------------------------------------------------- commit 7eca07ec271ebd4598d961a2609e646849fcb0ba Author: Jan Safranek <jsafrane(a)redhat.com> Date: Tue Sep 30 10:31:14 2014 +0200 Reduce TOC-depth in readthedocs pages. >--------------------------------------------------------------- doc/src/Makefile | 4 +++- 1 files changed, 3 insertions(+), 1 deletions(-) diff --git a/doc/src/Makefile b/doc/src/Makefile index a51f423..69d6135 100644 --- a/doc/src/Makefile +++ b/doc/src/Makefile @@ -42,7 +42,7 @@ index-man: subindexes-man # with one table of contents. index-%: subindexes-% ( \ - case "$*" in html) DEPTH=2; ;; *) DEPTH=3; ;; esac; \ + case "$*" in html) DEPTH=2; ;; rtd) DEPTH=2; ;; *) DEPTH=3; ;; esac; \ echo ".. toctree::"; \ echo " :maxdepth: $$DEPTH"; \ echo ""; \ @@ -68,6 +68,7 @@ shell-index-%: ( \ case "$*" in \ html) DEPTH=1; ;; \ + rtd) DEPTH=1; ;; \ *) DEPTH=2; ;; \ esac; \ echo ".. _lmi_shell:"; \ @@ -105,6 +106,7 @@ metacommand-index-%: ( \ case "$*" in \ html) DEPTH=1; ;; \ + rtd) DEPTH=1; ;; \ *) DEPTH=2; ;; \ esac; \ echo ".. _lmi_metacommand:"; \

1 0

[cura-tools] master: doc: moved commands directly under LMI metacommand heading (b4f8957)
by miminar＠fedoraproject.org 24 Sep '14

24 Sep '14

Repository : http://git.fedorahosted.org/cgit/cura-tools.git On branch : master >--------------------------------------------------------------- commit b4f89570281d51f0a233cdd201cf32cc84762802 Author: Michal Minar <miminar(a)redhat.com> Date: Wed Sep 24 13:54:18 2014 +0200 doc: moved commands directly under LMI metacommand heading >--------------------------------------------------------------- doc/src/Makefile | 10 +++++++--- doc/src/scripts/Makefile | 25 ++++--------------------- 2 files changed, 11 insertions(+), 24 deletions(-) diff --git a/doc/src/Makefile b/doc/src/Makefile index ede8b55..a51f423 100644 --- a/doc/src/Makefile +++ b/doc/src/Makefile @@ -8,11 +8,13 @@ PROJECTNAME := OpenLMITools 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 ALLSPHINXOPTS ?= -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . ALLSPHINXOPTS := $(TAGS) $(ALLSPHINXOPTS) -export WITH_COMMANDS OPENLMI_SCRIPTS_DIR +export WITH_COMMANDS OPENLMI_SCRIPTS_DIR COMMANDS .PHONY: clean deps @@ -28,7 +30,7 @@ latexpdf-build: latex-build @echo "latexpdf build finished" %-build: deps-% index-% - export SPHINXBUILD SRCDIR WITH_COMMANDS OPENLMI_SCRIPTS_DIR + export SPHINXBUILD SRCDIR WITH_COMMANDS OPENLMI_SCRIPTS_DIR COMMANDS ./build-with-sphinx.sh -b $* -t $*-build $(ALLSPHINXOPTS) $(BUILDDIR)/$* @echo "$* build finished. Output is in $(BUILDDIR)/$*." @@ -119,7 +121,9 @@ metacommand-index-%: echo " scripts/usage"; \ echo " scripts/configuration"; \ if [ $(WITH_COMMANDS) != 0 ]; then \ - echo " scripts/commands"; \ + for cmd in $(COMMANDS); do \ + echo " scripts/commands/$$cmd/cmdline.rst"; \ + done; \ fi; \ echo " scripts/development"; \ ) > metacommand-index.rst diff --git a/doc/src/scripts/Makefile b/doc/src/scripts/Makefile index d72592c..1b8796a 100644 --- a/doc/src/scripts/Makefile +++ b/doc/src/scripts/Makefile @@ -8,13 +8,9 @@ else endif BUILD ?= html -.PHONY: all devel clean devindex commands.txt commands.rst +.PHONY: all devel clean devindex commands.txt -ifeq ($(WITH_COMMANDS), 0) all: devel commands.txt devindex -else -all: devel commands.txt commands.rst devindex -endif devindex: ( \ @@ -46,32 +42,19 @@ else printf " * :ref:\`openlmi-scripts-$${cmd}-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: 1\n\n" >> $@ find $(OPENLMI_SCRIPTS_DIR)/commands -mindepth 1 -maxdepth 1 -type d | sort | \ while read cmdpath; \ - do \ - cmd=$$(basename $$cmdpath); \ - printf " commands/$${cmd}/cmdline.rst\n" >> $@; \ - ln -s "$${cmdpath}/doc" commands/$${cmd}; \ + do \ + ln -s "$${cmdpath}/doc" commands/$$(basename $$cmdpath); \ done endif clean: make -C devel clean - -rm commands.txt commands.rst development.rst + -rm commands.txt development.rst -rm -rf commands

1 0

[cura-tools] master: doc: restructured (cf2bb1c)
by miminar＠fedoraproject.org 24 Sep '14

24 Sep '14

Repository : http://git.fedorahosted.org/cgit/cura-tools.git On branch : master >--------------------------------------------------------------- commit cf2bb1c3dbaaf9552a0c78adf91d2bcf1c780f5c Author: Michal Minar <miminar(a)redhat.com> Date: Wed Sep 24 13:11:59 2014 +0200 doc: restructured Moved all API reference under top-level heading. Fixed some build issues. * tags were not passed correctly to sphinx LMIShell's and metacommand's api reference is generated by single script. >--------------------------------------------------------------- Makefile.inc | 2 +- cli/lmi/scripts/common/configuration.py | 7 -- doc/src/Makefile | 30 ++++-- doc/src/conf.py.skel | 17 ++-- doc/src/genapi.sh | 181 +++++++++++++++++++++++++++++++ doc/src/scripts/Makefile | 22 +--- doc/src/scripts/devel/Makefile | 10 +-- doc/src/scripts/devel/gendoc.sh | 75 ------------- doc/src/shell/Makefile | 11 -- doc/src/shell/generate_code.py | 37 ------- 10 files changed, 217 insertions(+), 175 deletions(-) diff --git a/Makefile.inc b/Makefile.inc index 64814cd..0b6a631 100644 --- a/Makefile.inc +++ b/Makefile.inc @@ -2,7 +2,7 @@ SELFDIR = $(dir $(lastword $(MAKEFILE_LIST))) ROOTDIR := $(SELFDIR) VERSION ?= $(shell PYTHONPATH=$(ROOTDIR)/cli python -c \ 'print(__import__("lmi.shell", fromlist=["__version__"]).__version__)') -TEMPLATES := $(wildcard *.py.skel) +TEMPLATES := $(shell find $(ROOTDIR) -name '*.py.skel') TARGETS := $(basename $(TEMPLATES)) .PHONY: setup clean-setup diff --git a/cli/lmi/scripts/common/configuration.py b/cli/lmi/scripts/common/configuration.py index f35e4c6..4e45ed7 100644 --- a/cli/lmi/scripts/common/configuration.py +++ b/cli/lmi/scripts/common/configuration.py @@ -14,13 +14,6 @@ # along with this program; if not, see <http://www.gnu.org/licenses/>. """ Module for Configuration class. - -Configuration ---------------------- - -.. autoclass:: Configuration - :members: - """ import os diff --git a/doc/src/Makefile b/doc/src/Makefile index 4ec89fa..ede8b55 100644 --- a/doc/src/Makefile +++ b/doc/src/Makefile @@ -3,10 +3,14 @@ include ../../Makefile.inc BUILDDIR ?= ../build SPHINXBUILD ?= sphinx-build -ALLSPHINXOPTS ?= -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . SRCDIR ?= ../../cli PROJECTNAME := OpenLMITools WITH_COMMANDS ?= 0 +ifeq ($(WITH_COMMANDS), 1) + TAGS := $(TAGS) -t with-commands +endif +ALLSPHINXOPTS ?= -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . +ALLSPHINXOPTS := $(TAGS) $(ALLSPHINXOPTS) export WITH_COMMANDS OPENLMI_SCRIPTS_DIR @@ -14,11 +18,9 @@ export WITH_COMMANDS OPENLMI_SCRIPTS_DIR deps: setup make -C scripts - make -C shell deps-%: setup BUILD=$* make -C scripts - BUILD=$* make -C shell latexpdf-build: latex-build sed -i 's/^\\makeindex$$/\0[columns=1]/' $(BUILDDIR)/latex/$(PROJECTNAME).tex @@ -44,6 +46,9 @@ index-%: subindexes-% echo ""; \ echo " shell-index"; \ echo " metacommand-index"; \ + if [ "$*" == html -o "$*" == rtd ]; then \ + echo " api"; \ + fi; \ ) > toc.txt if [ "$*" == html ]; then \ ln -sf index-$*.txt index.rst; \ @@ -54,7 +59,7 @@ index-%: subindexes-% subindexes-man: shell-index-man @echo "Built subindexes for man build." -subindexes-%: shell-index-% metacommand-index-% +subindexes-%: shell-index-% metacommand-index-% api-% @echo "Built subindexes for $* build." shell-index-%: @@ -89,9 +94,6 @@ shell-index-%: echo " shell/return_values"; \ echo " shell/interactive_interface"; \ echo " shell/builtins"; \ - if [ "$*" == html -o "$*" == rtd ]; then \ - echo " shell/code"; \ - fi; \ ) > shell-index.rst metacommand-index-man: @@ -122,7 +124,17 @@ metacommand-index-%: echo " scripts/development"; \ ) > metacommand-index.rst +api-html: deps-html api.rst + +api-rtd: deps-html api.rst + +api-%: + @echo "Skipping api reference" + +api.rst: genapi.sh $(shell find $(SRCDIR)/lmi/scripts -name '*.py' -type f) + ./genapi.sh + clean: clean-setup make -C scripts clean - make -C shell clean - -rm toc.txt *index.rst + -rm toc.txt *index.rst api.rst + -rm -rf api/ diff --git a/doc/src/conf.py.skel b/doc/src/conf.py.skel index b5923f1..2c9d300 100644 --- a/doc/src/conf.py.skel +++ b/doc/src/conf.py.skel @@ -52,9 +52,9 @@ def process_signature(app, what, name, obj, options, signature, return_annotatio def setup(app): # Register new option to include documentation for metacommand's commands - app.add_config_value('with_commands', False, 'env') + app.add_config_value('with_commands', False, True) # Register new option to include class list and class tree in index.rst - app.add_config_value('includeClasses', 'True', True) + app.add_config_value('includeClasses', True, True) # Register a very simple lexer for syntax highlighting of a shell samples app.add_lexer("shell", ShellLexer()) # autodoc setting for __init__() doc string @@ -70,8 +70,7 @@ with_commands = False # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. SRCDIR = os.environ.get('SRCDIR', '../../cli/lmi') -sys.path[0:0] = [os.path.abspath(os.path.join(SRCDIR, p)) for p in ( - 'scripts', 'shell')] +sys.path[0:0] = [SRCDIR] if tags.has('with-commands'): scripts_path = os.environ.get('OPENLMI_SCRIPTS_DIR', '../openlmi-scripts') @@ -79,11 +78,11 @@ if tags.has('with-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)) + if os.path.isdir(os.path.join(commands_dir, f)) ] + else: + commands = commands.split(',') + for i, cmd in enumerate(commands): + sys.path.insert(2 + i, os.path.join(os.path.abspath(commands_dir), cmd)) with_commands = True del scripts_path, commands, commands_dir diff --git a/doc/src/genapi.sh b/doc/src/genapi.sh new file mode 100755 index 0000000..f34ae9c --- /dev/null +++ b/doc/src/genapi.sh @@ -0,0 +1,181 @@ +#!/bin/bash +# Helper script for generating developer documentation in +# api/ and api.rst + +TOPDIR=../.. +DOCDIR=$TOPDIR/doc/src +SRCDIR=$TOPDIR/cli/lmi +WITH_COMMANDS=${WITH_COMMANDS:-0} + +function get_modules() { + pushd "$SRCDIR/$1" >/dev/null + find -type f -a -name '*.py' | \ + sed -e 's:/__init__\.py$::' -e 's:^./::' | \ + grep -v "^\.$" | \ + grep -v '$^\|/$_' | \ + sort -u + popd >/dev/null +} + +function get_module_name() { + path=`sed -e "s:^.*${SRCDIR}/$.*$$:\1:" -e "s:/:.:g"` + basename -s .py "$path" +} + +function get_version_string() { + pushd $TOPDIR/cli >/dev/null + out=`python setup.py --version` + git_version=`git describe HEAD 2>/dev/null` + echo -n "\`\`$out\`\`" + if [ -n "$git_version" ]; then + echo ", git: \`\`$git_version\`\`" + fi + popd >/dev/null +} + +function get_scripts_version_string() { + cat $OPENLMI_SCRIPTS_DIR/VERSION 2>/dev/null +} + +for dir in shell scripts/common; 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_ +OpenLMI Tools API reference +=========================== + +This is a generated documentation from *OpenLMI Tools* sources. + +Generated from version: $(get_version_string) + +.. only:: html + + **Contents:** + +.. toctree:: + :maxdepth: 2 + + api/shell + api/scripts +_EOF_ + +cat >$DOCDIR/api/shell.rst <<_EOF_ +LMIShell API reference +====================== + +This is a generated documentation from *LMIShell*'s sources. + +Generated from version: $(get_version_string) + +.. only:: html + + **Contents:** + +.. toctree:: + :maxdepth: 2 + +_EOF_ + +cat >$DOCDIR/api/scripts.rst <<_EOF_ +LMI Scripts API reference +========================= + +This is a generated documentation from *OpenLMI Scripts* sources. This covers +everything under :py:mod:\`lmi.scripts\` namespace. + +:py:mod:\`lmi.scripts.common\` package provides useful functionality for script +development. Various scripts share this directory in order to provide +command-line interface through *LMI metacommand*. + +Generated from version: $(get_version_string) + +.. ifconfig:: with_commands + + Scripts version: $(get_scripts_version_string) + +.. only:: html + + **Contents:** + +.. toctree:: + :maxdepth: 1 + + scripts/common +_EOF_ + +cat >$DOCDIR/api/scripts/common.rst <<_EOF_ +LMI Scripts common library reference +==================================== + +This library builds on top of *LMIShell*'s functionality. It provides various +utilities and wrappers for building command-line interfaces to *OpenLMI +Providers*. + +Generated from version: $(get_version_string) + +------------------------------------------------------------------------------- + +**Exported members:** + +.. automodule:: lmi.scripts.common + :members: + +------------------------------------------------------------------------------- + +**Submodules:** + +.. toctree:: + :maxdepth: 1 + +_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_ + $module + $underline + .. automodule:: lmi.shell.$module + :members: + _EOF_ +done + +# Generate api/scripts/common/*.rst +for module_path in `get_modules scripts/common`; do + 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/scripts/common.rst " common/$module" + cat >$DOCDIR/api/scripts/common/${module}.rst <<-_EOF_ + $module + $underline + .. automodule:: lmi.scripts.common.$module + :members: + _EOF_ +done + +# Add commands api reference to api/scripts.rst +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` + fi + + for cmd in $COMMANDS; do + link="api/scripts/$cmd" + echo >>$DOCDIR/api/scripts.rst " ../scripts/commands/$cmd/python" + done +fi diff --git a/doc/src/scripts/Makefile b/doc/src/scripts/Makefile index f612dc7..d72592c 100644 --- a/doc/src/scripts/Makefile +++ b/doc/src/scripts/Makefile @@ -27,9 +27,6 @@ devindex: echo " devel/basics"; \ echo " devel/command-classes"; \ echo " devel/command-properties"; \ - if [ "$(BUILD)" == html -o "$(BUILD)" == rtd ]; then \ - echo " devel/api"; \ - fi; \ ) > development.rst devel: @@ -46,7 +43,7 @@ ifeq ($(WITH_COMMANDS), 0) else ( \ for cmd in $(COMMANDS); do \ - printf " * :ref:\`openlmi-scripts-$${cmd}\`\n"; \ + printf " * :ref:\`openlmi-scripts-$${cmd}-cmd\`\n"; \ done; \ ) > $@ endif @@ -62,24 +59,13 @@ else mkdir commands echo "Usage and developer documentations for commands of *LMI metacommand*'s" >> $@ printf "\n.. toctree::\n" >> $@ - printf " :maxdepth: 2\n\n" >> $@ + printf " :maxdepth: 1\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; \ + printf " commands/$${cmd}/cmdline.rst\n" >> $@; \ + ln -s "$${cmdpath}/doc" commands/$${cmd}; \ done endif diff --git a/doc/src/scripts/devel/Makefile b/doc/src/scripts/devel/Makefile index dc35ec2..92fd071 100644 --- a/doc/src/scripts/devel/Makefile +++ b/doc/src/scripts/devel/Makefile @@ -8,13 +8,7 @@ DSTFIGS := $(patsubst %.svg,%.png,$(SRCFIGS)) .PHONY: help clean html -all: api.rst $(TUTORIAL_TARBALL) fig - -api.rst: gendoc.sh $(wildcard $(SRCDIR)/lmi/scripts/*.py \ - $(SRCDIR)/lmi/scripts/common/*.py \ - $(SRCDIR)/lmi/scripts/common/command/*.py \ - $(SRCDIR)/lmi/scripts/common/formatter/*.py) - ./gendoc.sh +all: $(TUTORIAL_TARBALL) fig fig: $(DSTFIGS) @@ -22,7 +16,7 @@ fig: $(DSTFIGS) convert $? $@ clean: - -rm -rf modules/ api.rst $(TUTORIAL_TARBALL) $(DSTFIGS) + -rm -rf $(TUTORIAL_TARBALL) $(DSTFIGS) $(TUTORIAL_TARBALL): tar -czf $@ mylf diff --git a/doc/src/scripts/devel/gendoc.sh b/doc/src/scripts/devel/gendoc.sh deleted file mode 100755 index 9c9dd05..0000000 --- a/doc/src/scripts/devel/gendoc.sh +++ /dev/null @@ -1,75 +0,0 @@ -#!/bin/bash - -# -# Helper script to generate developer documentation in -# modules/ and api.rst -# - -TOPDIR=../../../.. -DOCDIR=$TOPDIR/doc/src/scripts/devel -SRCDIR=$TOPDIR/cli/lmi/scripts - -[ -e $DOCDIR/modules ] || mkdir $DOCDIR/modules - -function get_modules() { - find $SRCDIR -type f -a -name '*.py' | \ - sed 's:/__init__\.py$::' | \ - grep -v "^${SRCDIR}/\?$" | \ - grep -v '/_' | \ - sort -u -} - -function get_module_name() { - path=`sed -e "s:^.*${SRCDIR}/$.*$$:\1:" -e "s:/:.:g"` - basename -s .py "$path" -} - -function get_version_string() { - pushd $TOPDIR/cli >/dev/null - out=`python setup.py --version` - git_version=`git describe HEAD 2>/dev/null` - echo -n "\`\`$out\`\`" - if [ -n "$git_version" ]; then - echo ", git: \`\`$git_version\`\`" - fi - popd >/dev/null -} - -# api.rst header -cat >$DOCDIR/api.rst <<_EOF_ -OpenLMI Scripts API -=================== - -This is a generated documentation form *OpenLMI Scripts* sources. - -Developer of script library will be interested in -:py:mod:\`lmi.scripts.common\` package providing useful functionality to -script development. - -Generated from version: $(get_version_string) - -.. only:: html - - **Contents:** - -.. toctree:: - :maxdepth: 2 - -_EOF_ - -# Generate modules/*.rst -for module_path in `get_modules`; do - module=`echo "$module_path" | get_module_name` - out=$module.rst - len=`echo $module| wc -c` - len=$(($len-1)) - underline="" - for i in `seq $len`; do underline="=$underline"; done - cat >$DOCDIR/modules/$out <<_EOF_ -$module -$underline -.. automodule:: lmi.scripts.$module - :members: -_EOF_ - echo >>$DOCDIR/api.rst " modules/$module" - done diff --git a/doc/src/shell/Makefile b/doc/src/shell/Makefile deleted file mode 100644 index 580245d..0000000 --- a/doc/src/shell/Makefile +++ /dev/null @@ -1,11 +0,0 @@ -SRCDIR ?= ../../../cli - -.PHONY: help clean html commands.rst - -all: code.rst - -code.rst: generate_code.py $(wildcard $(SRCDIR)/lmi/shell/*.py) - ./generate_code.py - -clean: - -rm -rf _code code.rst diff --git a/doc/src/shell/generate_code.py b/doc/src/shell/generate_code.py deleted file mode 100755 index 3b5925e..0000000 --- a/doc/src/shell/generate_code.py +++ /dev/null @@ -1,37 +0,0 @@ -#!/usr/bin/python - -import os -import sys - -mod_path = os.path.abspath("../../../cli/lmi/shell/") - -filt = lambda p: \ - p.endswith(".py") and \ - not p.startswith("_") and \ - p != "LMIShellVersion.py" -filenames = filter(filt, os.listdir(mod_path)) -filenames.sort() - -if not os.path.exists("_code"): - os.mkdir("_code") - -code_fout = open("code.rst", "w") -code_fout.write( - "API Documentation\n=================\n\n" - ".. toctree::\n" - " :maxdepth: 2\n\n") - -for filename in filenames: - module = str(filename[:-3]) - - code_fout.write(" _code/code_%s\n" % module) - - code_module_fout = open("_code/code_"+module+".rst", "w") - code_module_fout.write("%s Package\n" % module) - code_module_fout.write("=" * (len(module)+8) + "\n\n") - code_module_fout.write(".. automodule:: lmi.shell.%s\n" % module) - code_module_fout.write(" :members:\n") - code_module_fout.write(" :undoc-members:\n") - code_module_fout.close() - -code_fout.close()

1 0

[cura-tools] master: doc: allow to build documentation with commands (d56ebe9)
by miminar＠fedoraproject.org 24 Sep '14

24 Sep '14

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/openlmithe… +[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

1 0

[cura-tools] master: fixed setup command (6e7964b)
by miminar＠fedoraproject.org 24 Sep '14

24 Sep '14

Repository : http://git.fedorahosted.org/cgit/cura-tools.git On branch : master >--------------------------------------------------------------- commit 6e7964b32822f0e3d1f00e1afbfc52d817980f8f Author: Michal Minar <miminar(a)redhat.com> Date: Fri Sep 12 12:19:44 2014 +0200 fixed setup command Makefile did not read version of tools properly. >--------------------------------------------------------------- Makefile.inc | 3 ++- 1 files changed, 2 insertions(+), 1 deletions(-) diff --git a/Makefile.inc b/Makefile.inc index 7b8025c..64814cd 100644 --- a/Makefile.inc +++ b/Makefile.inc @@ -1,6 +1,6 @@ SELFDIR = $(dir $(lastword $(MAKEFILE_LIST))) ROOTDIR := $(SELFDIR) -VERSION ?= $(shell PYTHONPATH=$(ROOTDIR/cli) python -c \ +VERSION ?= $(shell PYTHONPATH=$(ROOTDIR)/cli python -c \ 'print(__import__("lmi.shell", fromlist=["__version__"]).__version__)') TEMPLATES := $(wildcard *.py.skel) TARGETS := $(basename $(TEMPLATES)) @@ -8,6 +8,7 @@ TARGETS := $(basename $(TEMPLATES)) .PHONY: setup clean-setup setup: $(TARGETS) + @echo "Written setup scripts with tools version = $(VERSION)." %.py: %.py.skel sed 's/@@VERSION@@/$(VERSION)/g' <$? >$@

1 0

[cura-tools] master: fix signal() behavior in non-main thread (8e7bf0f)
by phatina＠fedoraproject.org 19 Sep '14

19 Sep '14

Repository : http://git.fedorahosted.org/cgit/cura-tools.git On branch : master >--------------------------------------------------------------- commit 8e7bf0fddc8b86fdecd110dbf653bdd2ddb60aae Author: Peter Hatina <phatina(a)redhat.com> Date: Fri Sep 19 14:53:01 2014 +0200 fix signal() behavior in non-main thread >--------------------------------------------------------------- cli/lmi/shell/LMIMethod.py | 114 ++++++++++++++++++++++++++++--------------- 1 files changed, 74 insertions(+), 40 deletions(-) diff --git a/cli/lmi/shell/LMIMethod.py b/cli/lmi/shell/LMIMethod.py index b6f1775..988f9ab 100644 --- a/cli/lmi/shell/LMIMethod.py +++ b/cli/lmi/shell/LMIMethod.py @@ -54,46 +54,82 @@ from lmi.shell.LMIExceptions import * logger = logging.getLogger(__name__) -class LMISignalHelper(object): +class LMISignalHelperBase(object): """ - Helper class, which takes care of signal (de)registration and handling. + Base signal handling class. """ - _instance = None - - def __new__(cls): - if cls._instance is None: - cls._instance = super(LMISignalHelper, cls).__new__(cls) - LMISignalHelper.reset(cls._instance) - return cls._instance + @staticmethod + def signal(signo, handler): + """ + Calls signal() for signo, handler and returns the old signal handler. + If signo is list of signals, the signal() call is applied for each + signo. If handler is also list, each signal from signo will be handled + by corresponding handler. In such case, tuple of previous handlers will + be returned. + """ + if isinstance(signo, (list, tuple)): + if not isinstance(handler, (list, tuple)): + handler = [handler] * len(signo) + signo_handler = zip(signo, handler) + if not signo_handler: + return (None,) * len(signo) + old_handlers = [] + for signal, handler in signo_handler: + old_handlers.append( + LMISignalHelperBase.signal_core(signal, handler)) + return tuple(old_handlers) + else: + return LMISignalHelperBase.signal_core(signal, handler) - def reset(self): + @staticmethod + def signal_core(signo, handler): """ - Resets the single instance into default state. + Wrapper method for signal.signal(). In case of ValueError, it returns + None, old signal handler otherwise. If handler is None, default signal + handler is set for such signal. """ - self._handler_sigint = None - self._handler_sigterm = None + try: + if handler is None: + handler = signal.SIG_DFL + return signal.signal(signo, handler) + except ValueError: + return None + + +class LMIMethodSignalHelper(LMISignalHelperBase): + """ + Helper class which takes care of signal (de)registration and handling. + """ + + INTERRUPT_SIGNALS = ( + signal.SIGINT, + signal.SIGTERM) + + def __init__(self): + super(LMIMethodSignalHelper, self).__init__() self._signal_handled = False - self._instance._callbacks = collections.OrderedDict() + self._signal_prev_handlers = (signal.SIG_DFL,) * 2 + self._callbacks = collections.OrderedDict() def signal_attach(self): """ Registers *SIGINT* and *SIGTERM* signals to local handler in which, the flags for each signal are modified, if such signal is caught. """ + def handler(sig, action): + self.signal_handler(sig, action) + self._signal_handled = False - self._handler_sigint = signal.signal( - signal.SIGINT, LMISignalHelper.__signal_handler) - self._handler_sigterm = signal.signal( - signal.SIGTERM, LMISignalHelper.__signal_handler) + self._signal_prev_handlers = self.signal( + self.INTERRUPT_SIGNALS, handler) def signal_detach(self): """ Unregisters *SIGINT* and *SIGTERM* handler and removes all the attached callbacks. """ - signal.signal(signal.SIGINT, self._handler_sigint) - signal.signal(signal.SIGTERM, self._handler_sigterm) + self.signal(self.INTERRUPT_SIGNALS, self._signal_prev_handlers) def signal_handled(self): """ @@ -120,21 +156,17 @@ class LMISignalHelper(object): """ self._callbacks.pop(cb_name) - @staticmethod - def __signal_handler(signo, frame): + def signal_handler(self, signo, frame): """ Signal handler, which is called, when *SIGINT* and *SIGTERM* are sent to the LMIShell. :param int signo: signal number :param frame: -- stack frame - - **NOTE:** see help(signal) """ - if signo in (signal.SIGINT, signal.SIGTERM): - LMISignalHelper._instance._signal_handled = True - for cb in LMISignalHelper._instance._callbacks.values(): - cb() + if signo in self.INTERRUPT_SIGNALS: + self._signal_handled = True + [cb() for cb in self._callbacks.values()] class LMIMethod(LMIWrapperBaseObject): @@ -433,14 +465,15 @@ class LMIMethod(LMIWrapperBaseObject): # Register signal callback for SIGINT, SIGTERM with callback, # which awakes waiting thread for immediate return. - LMISignalHelper().callback_attach( + signal_helper = LMIMethodSignalHelper() + signal_helper.callback_attach( "indication", lambda: LMIMethod.__wake(cond)) - LMISignalHelper().signal_attach() + signal_helper.signal_attach() # Wait for the job to finish wake_cnt = 0 cond.acquire() - while not LMISignalHelper().signal_handled() and \ + while not signal_helper.signal_handled() and \ not job_finished.value and \ not lmi_is_job_finished(job_inst): cond.wait(LMIMethod._COND_WAIT_TIME) @@ -469,8 +502,8 @@ class LMIMethod(LMIWrapperBaseObject): break # Unregister signal handler - LMISignalHelper().signal_detach() - LMISignalHelper().callback_detach("indication") + signal_helper.signal_detach() + signal_helper.callback_detach("indication") cond.release() @@ -480,7 +513,7 @@ class LMIMethod(LMIWrapperBaseObject): self._conn.client.delete_instance(cim_handler.path) if job_exception.value: raise job_exception.value - if LMISignalHelper().signal_handled() and not job_finished.value: + if signal_helper.signal_handled() and not job_finished.value: # We got SIGINT or SIGTERM, when waiting for the job, cancelling # the job logger.warn("Cancelling a job '%s'" % job_inst.Name) @@ -506,9 +539,10 @@ class LMIMethod(LMIWrapperBaseObject): # Register signal callback for SIGINT, SIGTERM with callback, # which awakes waiting thread for immediate return. - LMISignalHelper().callback_attach( + signal_helper = LMIMethodSignalHelper() + signal_helper.callback_attach( "polling", lambda: LMIMethod.__wake(cond)) - LMISignalHelper().signal_attach() + signal_helper.signal_attach() cond = threading.Condition() cond.acquire() @@ -517,7 +551,7 @@ class LMIMethod(LMIWrapperBaseObject): try: sleep_time = 1 - while not LMISignalHelper().signal_handled() and \ + while not signal_helper.signal_handled() and \ not lmi_is_job_finished(job_inst): # Sleep, a bit longer in every iteration cond.wait(sleep_time) @@ -539,10 +573,10 @@ class LMIMethod(LMIWrapperBaseObject): cond.release() # Unregister signal handler and callback - LMISignalHelper().signal_detach() - LMISignalHelper().callback_detach("polling") + signal_helper.signal_detach() + signal_helper.callback_detach("polling") - if LMISignalHelper().signal_handled() and \ + if signal_helper.signal_handled() and \ not lmi_is_job_finished(job_inst): # We got SIGINT or SIGTERM, when waiting for the job, cancelling # the job

1 0

[cura-tools] master: Add readthedocs target to makefiles. (6353405)
by jsafrane＠fedoraproject.org 17 Sep '14

17 Sep '14

Repository : http://git.fedorahosted.org/cgit/cura-tools.git On branch : master >--------------------------------------------------------------- commit 6353405e63aeb711a3a68bb317349763c4f1e2a2 Author: Jan Safranek <jsafrane(a)redhat.com> Date: Wed Sep 17 12:30:00 2014 +0200 Add readthedocs target to makefiles. For readthedocs.org, we do not want Contents, Tables and indices and similar chapters (i.e. we want the same as e.g. epub target), however we *do* want to include developer API documentation. Therefore include shell/code and scripts/devel/api in the 'rtd' target. >--------------------------------------------------------------- doc/README.md | 6 +++++- doc/src/Makefile | 2 +- doc/src/scripts/Makefile | 2 +- 3 files changed, 7 insertions(+), 3 deletions(-) diff --git a/doc/README.md b/doc/README.md index 65a93d3..f17bd9b 100644 --- a/doc/README.md +++ b/doc/README.md @@ -5,7 +5,11 @@ It's available online on [pythonhosted][]. How to build ------------ -Supported builds are *html*, *pdflatex* and *epub*. +Supported builds are *html*, *pdflatex*, *epub* and *rtd*. + +*rtd* build is similar to *html*, i.e. generates html files, however these +files are intended to be included in overall OpenLMI documentation on +readthedocs.org. It ommits several chapters, which would clutter navigation. ### Requirements diff --git a/doc/src/Makefile b/doc/src/Makefile index c73aa55..a4db2d0 100644 --- a/doc/src/Makefile +++ b/doc/src/Makefile @@ -86,7 +86,7 @@ shell-index-%: echo " shell/return_values"; \ echo " shell/interactive_interface"; \ echo " shell/builtins"; \ - if [ "$*" == html ]; then \ + if [ "$*" == html -o "$*" == rtd ]; then \ echo " shell/code"; \ fi; \ ) > shell-index.rst diff --git a/doc/src/scripts/Makefile b/doc/src/scripts/Makefile index 6f3afd4..716e35b 100644 --- a/doc/src/scripts/Makefile +++ b/doc/src/scripts/Makefile @@ -17,7 +17,7 @@ devindex: echo " devel/basics"; \ echo " devel/command-classes"; \ echo " devel/command-properties"; \ - if [ "$(BUILD)" == html ]; then \ + if [ "$(BUILD)" == html -o "$(BUILD)" == rtd ]; then \ echo " devel/api"; \ fi; \ ) > development.rst

1 0

[cura-tools] master: fix missing indication reply (2ae0c00)
by phatina＠fedoraproject.org 16 Sep '14

16 Sep '14

Repository : http://git.fedorahosted.org/cgit/cura-tools.git On branch : master >--------------------------------------------------------------- commit 2ae0c00ab09d5ae31f19d65c2fc442ba4d1648e5 Author: Peter Hatina <phatina(a)redhat.com> Date: Mon Sep 15 20:34:44 2014 +0200 fix missing indication reply >--------------------------------------------------------------- cli/lmi/shell/compat/CIMIndicationListener.py | 49 +++++++ cli/lmi/shell/compat/http.py | 189 +++++++++++++++++++++++++ 2 files changed, 238 insertions(+), 0 deletions(-) diff --git a/cli/lmi/shell/compat/CIMIndicationListener.py b/cli/lmi/shell/compat/CIMIndicationListener.py index d2d939e..9f717f8 100644 --- a/cli/lmi/shell/compat/CIMIndicationListener.py +++ b/cli/lmi/shell/compat/CIMIndicationListener.py @@ -22,12 +22,15 @@ import socket import string import threading +from xml.sax.saxutils import escape + from SocketServer import BaseRequestHandler from SocketServer import ThreadingMixIn from BaseHTTPServer import HTTPServer from BaseHTTPServer import BaseHTTPRequestHandler from lmi.shell.LMIExceptions import ConnectionError +from lmi.shell.compat import http class CIMIndicationHandlerCallback(object): @@ -55,6 +58,43 @@ class CIMIndicationHandler(ThreadingMixIn, BaseHTTPRequestHandler): """ CIMLISTENER_PREFIX = "/CIMListener" + @staticmethod + def make_indication_response(cim_version, dtd_version, message_id, + protocol_version): + """ + Returns CIM-XML indication response with CIM, DTD, Protocol version + and Message ID filled. + """ + return "<?xml version=\"1.0\" encoding=\"utf-8\" ?>\n" \ + "<CIM CIMVERSION=\"%s\" DTDVERSION=\"%s\">\n" \ + "<MESSAGE ID=\"%s\" PROTOCOLVERSION=\"%s\">\n" \ + "<SIMPLEEXPRSP>\n" \ + "<EXPMETHODRESPONSE NAME=\"ExportIndication\">\n" \ + "</EXPMETHODRESPONSE>\n" \ + "</SIMPLEEXPRSP>\n" \ + "</MESSAGE>\n" \ + "</CIM>\n" % tuple(escape(arg) for arg in ( + cim_version, dtd_version, message_id, protocol_version)) + + def send_indication_response(self, response): + """ + Sends indication response. + """ + http_version = self.request_version + http_response = http.HTTPResponse(200, http_version, wfile=self.wfile) + http_response[http.HEADER_NAME_CONTENT_TYPE] = http.HEADER_VALUE_CONTENT_TYPE + if http_version == http.HTTP_1_1: + http_response[http.HEADER_NAME_TRANSFER_ENCODING] = http.HEADER_VALUE_CHUNKED + else: + http_response[http.HEADER_NAME_CONTENT_LENGTH] = len(response) + http_response[http.HEADER_NAME_CIM_EXPORT] = http.HEADER_VALUE_CIM_EXPORT_METHOD_RESPONSE + http_response[http.HEADER_NAME_TRAILER] = ", ".join([ + http.HEADER_VALUE_CIM_STATUS_CODE, + http.HEADER_VALUE_CIM_STATUS_CODE_DESCRIPTION, + http.HEADER_VALUE_CONTENT_LANGUAGE]) + http_response.body = response + http_response.send() + def do_POST(self): """ Overridden method, which is called, when a indication is received. It @@ -101,6 +141,15 @@ class CIMIndicationHandler(ThreadingMixIn, BaseHTTPRequestHandler): if "NewIndication" in ind_dict: ind = ind_dict["NewIndication"] + # Inform the CIMOM, that we got the indication. + cim_version = tt[1]["CIMVERSION"] + dtd_version = tt[1]["DTDVERSION"] + message_id = message[1]["ID"] + protocol_version = message[1]["PROTOCOLVERSION"] + self.send_indication_response( + self.make_indication_response( + cim_version, dtd_version, message_id, protocol_version)) + path = self.path cimlistener_ind = path.find(self.CIMLISTENER_PREFIX) if cimlistener_ind != -1: diff --git a/cli/lmi/shell/compat/http.py b/cli/lmi/shell/compat/http.py new file mode 100644 index 0000000..1d86154 --- /dev/null +++ b/cli/lmi/shell/compat/http.py @@ -0,0 +1,189 @@ +# Copyright (C) 2012-2014 Peter Hatina <phatina(a)redhat.com> +# +# This program is free software; you can redistribute it and/or +# modify it under the terms of the GNU General Public License +# as published by the Free Software Foundation; either version 2 +# of the License, or (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, see <http://www.gnu.org/licenses/>. + +from abc import ABCMeta +from abc import abstractmethod +from collections import OrderedDict +from BaseHTTPServer import BaseHTTPRequestHandler + +# HTTP responses dict. +responses = BaseHTTPRequestHandler.responses + +# HTTP string versions +HTTP_0_9 = "HTTP/0.9" +HTTP_1_0 = "HTTP/1.0" +HTTP_1_1 = "HTTP/1.1" + +# HTTP headers with values. +HEADER_NAME_CIM_EXPORT = "CIMExport" +HEADER_NAME_CONTENT_LENGTH = "Content-Length" +HEADER_NAME_CONTENT_TYPE = "Content-Type" +HEADER_NAME_TRAILER = "Trailer" +HEADER_NAME_TRANSFER_ENCODING = "transfer-encoding" +HEADER_VALUE_CIM_EXPORT_METHOD_RESPONSE = "MethodResponse" +HEADER_VALUE_CHUNKED = "chunked" +HEADER_VALUE_CIM_STATUS_CODE = "CIMStatusCode" +HEADER_VALUE_CIM_STATUS_CODE_DESCRIPTION = "CIMStatusCodeDescription" +HEADER_VALUE_CONTENT_LANGUAGE = "Content-Language" +HEADER_VALUE_CONTENT_TYPE = "application/xml; charset=utf-8" + +CRLF = "\r\n" + + +class HTTPBase(object): + """ + Base class for HTTP messages. + """ + def __init__(self, wfile): + self.wfile = wfile + + +class HTTPMessage(HTTPBase): + """ + Class for sending a HTTP message. + """ + __metaclass__ = ABCMeta + + # RFC 2616 doesn't define chunk size limit. Let's pick one. + CHUNK_MAX = 4 * 1024 + + def __init__(self, http_version, headers=None, body=None, wfile=None): + super(HTTPMessage, self).__init__(wfile) + self.http_version = http_version + self.headers = OrderedDict(headers or {}) + self.body = body or "" + + def __getitem__(self, name): + """ + Returns a HTTP header. + """ + return self.headers[name] + + def __setitem__(self, name, value): + """ + Updates or adds a new HTTP header. + """ + self.headers[name] = value + + @staticmethod + def is_message_chunked(headers): + """ + Returns True, if the headers contain "chunked" encoding entry. + """ + return headers.get( + HEADER_NAME_TRANSFER_ENCODING) == \ + HEADER_VALUE_CHUNKED + + def send_crlf(self): + """ + Sends CRLF symbols. + """ + self.wfile.write(CRLF) + + def send_chunk(self, chunk=""): + """ + Sends a one chunk of the message. + """ + self.wfile.write("%x" % len(chunk)) + self.wfile.write(CRLF) + self.wfile.write(chunk) + self.wfile.write(CRLF) + + def send_message_body(self, body): + """ + Sends a response body. + """ + if not self.is_message_chunked(self.headers) or \ + self.http_version != HTTP_1_1: + self.wfile.write(body) + else: + pos = 0 + msg_len = len(body) + while pos < msg_len: + if msg_len - pos >= self.CHUNK_MAX: + to_send = self.CHUNK_MAX + else: + to_send = msg_len - pos + # Send a chunk of data. + self.send_chunk(body[pos:pos+to_send]) + pos += to_send + + # Terminating chunk + self.send_chunk() + + def send_header(self, name, value): + """ + Sends a HTTP header. + """ + if self.http_version == HTTP_0_9: + return + self.wfile.write("%s: %s" % (name, value)) + self.send_crlf() + + def send_end_headers(self): + """ + Sends HTTP headers terminator. + """ + if self.http_version == HTTP_0_9: + return + self.send_crlf() + + def send_message_headers(self, headers): + """ + Sends HTTP headers. + """ + for name, value in headers.iteritems(): + self.send_header(name, value) + self.send_end_headers() + + @abstractmethod + def send(self, *args, **kwargs): + """ + Sends either HTTP message. + """ + pass + + +class HTTPResponse(HTTPMessage): + """ + HTTP Response class. + """ + def __init__(self, code, http_version, headers=None, body=None, wfile=None): + super(HTTPResponse, self).__init__(http_version, headers, body, wfile) + self.code = code + + def send_message_response_line(self, http_version, code): + """ + Sends a HTTP response status line. + """ + if http_version in (HTTP_1_0, HTTP_1_1): + self.wfile.write("%s %d" % (http_version, code)) + if code in responses: + self.wfile.write(" %s" % responses[code][0]) + self.send_crlf() + elif http_version == HTTP_0_9: + self.wfile.write("%s %d" % (http_version, code)) + self.send_crlf() + + def send(self, wfile=None): + """ + Sends a response header and message. + """ + if wfile is not None: + self.wfile = wfile + assert self.wfile is not None, "wfile can't be None" + self.send_message_response_line(self.http_version, self.code) + self.send_message_headers(self.headers) + self.send_message_body(self.body)

1 0

[cura-tools] master: documentation overhaul (e4585db)
by miminar＠fedoraproject.org 11 Sep '14

11 Sep '14

Repository : http://git.fedorahosted.org/cgit/cura-tools.git On branch : master >--------------------------------------------------------------- commit e4585db4bbe726d6343a0b337a599de5d3981763 Author: Michal Minar <miminar(a)redhat.com> Date: Tue Sep 9 15:56:04 2014 +0200 documentation overhaul Restructured whole documentation. Lot of corrections and style improvements in scripts documentation. Makefiles control the build. They generate index files and table of contents. Html build makes an index.rst composed of shell-index.rst and metacommand-index.rst with single table of contents of depth 1. It's the only build with autogenerated doc out of source code. Man page build makes the index.rst of just shell-index.rst. Man page of LMI metacommand is build separately. Latex and other builds again contain both shell's and metacommand's documentation. No autogerated documentation is included. >--------------------------------------------------------------- Diff suppressed because of size. To see it, use: git diff --patch-with-stat --no-color --find-copies-harder --ignore-space-at-eol ^e4585db4bbe726d6343a0b337a599de5d3981763~1 e4585db4bbe726d6343a0b337a599de5d3981763

1 0

[cura-tools] master: fix non-interactive LMIFormatter.fancy_format() (2354ffe)
by phatina＠fedoraproject.org 03 Sep '14

03 Sep '14

Repository : http://git.fedorahosted.org/cgit/cura-tools.git On branch : master >--------------------------------------------------------------- commit 2354ffe8127a7a2ea2a3136a738fb001d0ccab31 Author: Peter Hatina <phatina(a)redhat.com> Date: Wed Sep 3 10:02:03 2014 +0200 fix non-interactive LMIFormatter.fancy_format() >--------------------------------------------------------------- cli/lmi/shell/LMIFormatter.py | 2 +- 1 files changed, 1 insertions(+), 1 deletions(-) diff --git a/cli/lmi/shell/LMIFormatter.py b/cli/lmi/shell/LMIFormatter.py index 01885e5..2e9934f 100644 --- a/cli/lmi/shell/LMIFormatter.py +++ b/cli/lmi/shell/LMIFormatter.py @@ -145,7 +145,7 @@ class LMIFormatter(object): subprocess.call(subprocess_params) os.remove(tmpfile[1]) else: - self.format(0, 0, self._width) + self.format(0, self._width) class LMIMethodFormatter(LMIFormatter):

1 0

2024

2023

2022

2021

2020

2019

2018

2017

2016

2015

2014

2013

2012

cura-tools-devel September 2014